{
  "markdown": "# Agency\n\n![Agency](./media/logo.svg)\n\n[![npm](https://img.shields.io/npm/v/agency-cli.svg?logo=npm&label=npm)](https://www.npmjs.com/package/agency-cli)\n![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-green)\n\nAgency is an AI agent orchestrator running purely in the command line.\n\n- User-friendly TUI heavily inspired by [Lazygit](https://github.com/jesseduffield/lazygit)\n- CLI commands for easy automation\n- Supports any CLI coding agent: [Claude Code](https://github.com/anthropics/claude-code), [Codex CLI](https://github.com/openai/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [OpenCode](https://github.com/sst/opencode) and [you can add more](#defining-a-custom-agent)\n- Isolated environments for each task using [Git Worktrees](https://git-scm.com/docs/git-worktree) and [Tmux](https://github.com/tmux/tmux)\n\n## Getting Started\n\n1. Install Agency with your preferred method (macOS and Linux supported)\n   - NPM: `npm install -g agency-cli`\n   - Homebrew : `brew install tobias-walle/tap/agency`\n   - Build from source: `cargo install --git https://github.com/tobias-walle/agency`\n2. Set up your preferences: `agency setup`\n3. Set up Agency in your project: `agency init`\n4. Start the TUI: `agency`\n\n## TUI or CLI: your choice\n\nThe easiest option is to use the TUI; run `agency tui` or just `agency`.\n\n![TUI](./media/tui.png)\n\nEverything available in the TUI is also available via the CLI:\n\n- `agency --help` - See all available commands\n- `agency new my-task` - Create a new task with slug `my-task`, start a session for it, and attach immediately (no editor by default).\n- `agency new --draft my-task` - Create a new task as a draft (doesn't start or attach; in interactive TTY mode without a description, this opens your editor to write the initial instructions).\n- `agency edit my-task` - Edit a draft task.\n- `agency start my-task` - Start a task that is a draft or stopped.\n- `agency attach my-task` or `agency attach 1` - Open the agent TUI by slug or ID.\n- `agency attach --follow` - Attach to the focused task in a running Agency TUI.\n- `agency stop my-task` - Stop a running task (keep its worktree and branch).\n- `agency merge my-task` - Merge the task back into the base branch.\n- `agency path my-task` - Get the worktree path for a task.\n- `agency shell my-task` - Open a shell in the task's worktree.\n- `agency tasks` - List all tasks and their status.\n- `agency config` - Open the global Agency config in your editor.\n- `agency daemon start|stop|restart` - Manage the background daemon that tracks sessions and notifies clients.\n- ... and many more (see `agency --help`).\n\n## Skills\n\nTeach your AI coding agent how to use Agency by installing the Agency skill. Once installed, your agent will know how to parallelize tasks using Agency when you ask it to.\n\n### Claude Code\n\n```bash\n/plugin marketplace add tobias-walle/agency\n/plugin install agency@agency\n```\n\n```bash\n# Alternative: install via Agency CLI\nagency skill install\n# When prompted, select: \"Claude (~/.claude/skills)\"\n```\n\n### Codex CLI and Others\n\n```bash\nagency skill install\n# When prompted, select: \"Codex (~/.codex/skills)\" or a custom path\n```\n\n## Configuration\n\nConfiguration is layered in three tiers:\n\n1. Defaults (see [crates/agency/defaults/agency.toml](./crates/agency/defaults/agency.toml) or `agency defaults`)\n2. Global file `~/.config/agency/agency.toml` (created by `agency setup`)\n3. Project overrides at `./.agency/agency.toml`\n\n### Tmux\n\nAgency uses Tmux to manage the background agents.\n\nIf you attach to an agent you are basically opening Tmux.\n\nConfig precedence when starting sessions:\n\n1. User defaults (best-effort): `~/.tmux.conf`, then `~/.config/tmux/tmux.conf`\n2. Agency defaults (baseline UI/options applied programmatically)\n3. Agency global overrides: `~/.config/agency/tmux.conf`\n4. Project overrides: `./.agency/tmux.conf`\n\n### Defining a custom agent\n\nYou can define custom agents using any CLI command.\n\n```toml\n[agents.my-agent]\ncmd = [\"my-agent\", \"-p\", \"$AGENCY_TASK\"]\n```\n\nThe following environment variables are injected into the command:\n\n- `$AGENCY_TASK` - The full prompt for the current task.\n- `$AGENCY_ROOT` - The path to the folder of the main repo (not the worktree).\n- `$AGENCY_TASK_ID` - The numeric ID of the task.\n\nYou can also use the `<root>` placeholder for relative paths (works in any config in which you define a path).\n\n```toml\n[agents.my-local-agent]\ncmd = [\"<root>./my-local-agent\", \"-p\", \"$AGENCY_TASK\"]\n```\n\nCheck out the [default config](./crates/agency/defaults/agency.toml) for a few examples.\n\n### Editor\n\nControl which editor Agency uses when opening files (e.g. task descriptions, worktrees, and config):\n\n```toml\n# Preferred editor argv. If unset, Agency falls back to $EDITOR, then to `vi`.\neditor = [\"nvim\"]\n\n# Examples:\n# editor = [\"code\", \"-w\"]\n# editor = [\"zed\", \"--wait\"]\n```\n\nYou can also run `agency config` to open (and create if missing) the global config file directly in your editor.\n\n## Architecture\n\nAgency uses a daemon + client architecture with tmux-managed sessions. The daemon is slim: it computes session/task status from tmux and broadcasts notifications. Clients (CLI or TUI) communicate with the daemon via a Unix socket but attach directly to tmux for interactive views.\n\nDaemon socket path precedence:\n\n- `$AGENCY_SOCKET_PATH` env override\n- `daemon.socket_path` in config\n- `$XDG_RUNTIME_DIR/agency.sock`\n- `~/.local/run/agency.sock` (Default)\n\nTmux socket path precedence (used for all sessions):\n\n- `$AGENCY_TMUX_SOCKET_PATH` env override\n- `daemon.tmux_socket_path` in config\n- `$XDG_RUNTIME_DIR/agency-tmux.sock`\n- `~/.local/run/agency-tmux.sock` (Default)\n\n```mermaid\nflowchart LR\n  U[User] --> C[TUI/CLI]\n  C <--> S[Unix Socket]\n  S <--> D[Agency Daemon]\n  C <--> T[tmux Server]\n  D <--> T\n  T --> A[CLI Agents]\n\n  subgraph Project\n    A\n  end\n```\n\nFor example, when creating a new task the message flow between daemon and client looks like this:\n\n```mermaid\nsequenceDiagram\n  participant U as User\n  participant C as Agency CLI\n  participant D as Daemon\n  participant T as tmux\n  participant A as Agent\n\n  U->>C: agency new my-task\n  C->>C: Create .agency/tasks/my-task.md\n  C->>T: new-session -d -s agency-<id>-<slug> (remain-on-exit)\n  T->>A: Exec agent cmd in worktree\n  C->>T: attach-session -t agency-<id>-<slug>\n  U<<->>T: Terminal I/O\n  T->>D: (indirect) State via list-sessions/list-panes\n  D->>C: SessionsChanged/TasksChanged\n```\n",
  "bytes": 6473,
  "sha": "f71ec62f83d3f5a60fe7c5e68ee5a1ff731a083178284d43b0ee98efec324aef",
  "repo_slug": "tobias-walle/agency",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_tobias_walle_agency_skills_agency_main_dc962cfc/readme"
}