Agent Profile Documentation

Comprehensive command reference, configuration specification, and operator manual.

Quickstart: Everyday Workflow

Agent Profile selects profiles based on the canonical Git repository you are in. When you launch without a profile name, the tool resolves it automatically:

# 1. Enter your project directory:
cd ~/dev/client-portal

# 2. Link this repository to a dedicated profile:
agent-profile link client-portal

# 3. Launch your coding agent (it automatically uses the client-portal profile):
agent-profile claude

# 4. Pass arguments directly to the underlying agent after --:
agent-profile claude -- --model claude-3-7-sonnet

# 5. Check what would be selected without launching anything:
agent-profile claude resolve
agent-profile status

Complete CLI Command Reference

1. Launching Agents

agent-profile <agent> [<profile>] [OPTIONS] [-- <agent args...>]

Launches <agent> inside <profile>. If <profile> is omitted, resolves from repository mapping or default_profile. Profiles are automatically materialized on first launch.

  • --dry-run: Emits the calculated LaunchPlan without launching the agent or modifying filesystem state.
  • --repo <path>: Evaluates resolution as if operating from <path> rather than the current working directory.
  • -- <args...>: Passes all subsequent arguments directly to the agent binary verbatim.

2. Repository Mapping & Status

agent-profile [<agent>] status [--repo <path>] [--json]
agent-profile <agent> resolve [--repo <path>] [--json]
agent-profile <agent> current [--repo <path>]
agent-profile [<agent>] link <profile> [--repo <path>]
agent-profile [<agent>] unlink [--repo <path>]
agent-profile repositories [--json]
  • status: Displays current repository root, linked profile, and adapter availability.
  • resolve: Explains the exact precedence step that selected the active profile.
  • link: Binds the canonical root to a profile. Specifying <agent> link creates an agent-specific override.
  • unlink: Clears the stored mapping for this repository.
  • repositories: Lists all stored mappings with their health state (active, moved, not_a_repository, missing, unreadable, foreign).

3. Profile Lifecycle Management

agent-profile <agent> create <profile>
agent-profile <agent> delete <profile> [--yes]
agent-profile [<agent>] list [--json]
agent-profile profiles [--json]
agent-profile agents [--json]
  • create: Explicitly creates the profile directory and configuration skeleton.
  • delete: Removes a profile directory. Requires confirmation unless --yes is passed. Rejects deletion if any active repository mapping references the profile.
  • profiles: Lists all materialized profiles across all installed agents.
  • agents: Lists all twelve supported agents, PATH resolution, and isolation matrix.

4. Diagnostics & Shell Completions

agent-profile doctor [--repo <path>] [--json]
agent-profile <agent> doctor [<profile>] [--repo <path>] [--json]
agent-profile completions <bash|zsh|fish|powershell|elvish>
  • doctor: Verifies binary paths, configuration permissions, Git canonicalization, and repository integrity.
  • completions: Generates native shell autocompletions for all subcommands, agents, and local profiles.

Configuration & Filesystem Layout

All state lives locally in ~/.agent-profile/ (or %USERPROFILE%\.agent-profile\ on Windows). Override with the AGENT_PROFILE_HOME environment variable:

~/.agent-profile/
├── config.toml            # Global configuration (default_profile, logging)
├── repositories.toml      # Stored canonical repository mappings
└── profiles/
    ├── personal/
    │   ├── claude/        # CLAUDE_CONFIG_DIR
    │   └── codex/         # CODEX_HOME
    └── client-acme/
        ├── claude/
        └── codex/

Sample config.toml

# ~/.agent-profile/config.toml
default_profile = "personal"

[logging]
level = "warn"

Authoring New Agent Adapters

Adding support for a new coding agent requires implementing the AgentAdapter trait in Rust. Adapters calculate launch parameters as pure functions without side effects:

pub trait AgentAdapter: Send + Sync {
    /// Canonical agent identifier (e.g. "claude", "codex")
    fn name(&self) -> &'static str;

    /// Primary isolation mechanism description
    fn mechanism(&self) -> Mechanism;

    /// Synthesize an immutable LaunchPlan for the target profile
    fn synthesize(&self, profile_dir: &Path, args: &[String]) -> Result<LaunchPlan, AdapterError>;

    /// Audit executable availability and environment health
    fn doctor(&self) -> DiagnosticReport;
}

Authoritative References