# Agent Farm — complete website --- --- [Open source](https://github.com/dcouple/agent-farm) # Your agents. Your setup. Switch setups for Claude Code and Codex. Save a profile, pick it, launch in your native terminal. [Get started](https://getagentfarm.com/#get-started) [View on GitHub](https://github.com/dcouple/agent-farm) After installation `agent-farm init` [Meet the building blocks](https://getagentfarm.com/#how-it-works) ![A cozy pixel-art workbench: four setup cards connect to a cream terminal, framed by plants, books, and a sleeping cat.](https://getagentfarm.com/images/workbench-1254-7426a089c2.webp) agent-farm $ agent-farm Choose a profile Click or ↑↓ + Enter 01 / Overview ## Your setup, in one place. ![A pixel-art farm shed with four compartments: profile cards, robot agents, skill books, and workspace toolboxes.](https://getagentfarm.com/images/configuration-1400-b8f6d80e68.webp) Profile — a saved setup Agent — the worker Skill — the playbook Workspace — the tools 02 / Get started ## From setup to session. Save a profile. Point it at your repo. Launch Claude Code or Codex. After installation Set up once ``` agent-farm init ``` Pick a profile and launch ``` agent-farm ``` Install from source Requires Node.js 22.15+, pnpm, macOS or Linux, and an authenticated Claude Code or Codex CLI. Install Agent Farm ``` git clone https://github.com/dcouple/agent-farm.git cd agent-farm pnpm install --frozen-lockfile && pnpm build mkdir -p ~/.local/bin ln -s "$PWD/dist/cli.js" ~/.local/bin/ agent-farm ``` Add `~/.local/bin` to your shell’s `PATH`, then run `agent-farm init`. [Full installation guide](https://github.com/dcouple/agent-farm#install) --- Agent Farm / Field notes 01 # A setup for every kind of work. A planner needs different instructions from an implementer. Save those choices once, then take the right setup into your next repository. The toolkit ## Small pieces. Useful together. * ### [Switch profiles](https://getagentfarm.com/configuration#profiles) Choose a saved agent with its own model, instructions, and skills. * ### [Set up interactively](https://github.com/dcouple/agent-farm#install) Let init check prerequisites and install your starting profiles and skills. * ### [Connect a workspace](https://getagentfarm.com/guide#workspaces) Bring a project’s remote or local MCP tools into a launch. * ### [Manage global skills](https://getagentfarm.com/configuration#global-skills) Load a profile’s skills into your native user directory across repositories. * ### [Install configuration plugins](https://getagentfarm.com/configuration#plugins) Share versioned profiles, agents, and skills; detect conflicts with local edits. * ### [Run headlessly](https://getagentfarm.com/configuration#headless) Use headless execution with an initial message for scripted work. * ### [Declare child agents](https://github.com/dcouple/agent-farm/blob/main/CONFIGURATION.md#agents) Choose native delegation or a separately launched process for each child. * ### [Use either harness](https://getagentfarm.com/compare) Launch Claude Code or Codex with the configuration your agent selects. * ### [Inspect before launching](https://getagentfarm.com/configuration#inspect) Preview a profile’s settings, connections, and source files. * ### [Keep repository context](https://github.com/dcouple/agent-farm/blob/main/CONFIGURATION.md#workspaces-and-repositories) Work alongside the repo’s own AGENTS.md, CLAUDE.md, and references. From setup to session ## Four choices. Then you’re in. After `agent-farm init`, launch the interactive picker with `agent-farm`. This illustrated sequence shows the path to a session. 1. 01 / Profile ``` $ agent-farm › planner implementer reviewer ``` ### Pick a profile Choose the worker and playbooks for this job. 2. 02 / Workspace · optional ``` Project tools None › my-project MCP connections included ``` ### Add a workspace Choose project connections when you need them. 3. 03 / Repository ``` Working directory ~/repos/my-app Profile + tools + repo ✓ ``` ### Point at your repo Choose where the agent will read and work on files. 4. 04 / Native session ``` .agent-farm/generated/ instructions · skills · tools Claude Code or Codex → ``` ### Open your terminal Agent Farm builds the bundle and opens the selected native CLI. Illustrative screens. Your installed profiles and workspaces determine the choices shown. Already know your setup? ``` agent-farm run planner --workspace my-project ``` Review the [launch permissions](https://github.com/dcouple/agent-farm/blob/main/docs/operations.md) before your first run. The same worker, more context ## Give the project a toolbox. A repository tells the agent where to work. A workspace supplies named connections to external tools, independently of that folder. Profile + repository ### Work from the repository. * Your selected model and instructions * Selected skills and child agents * Repository files and local context For example: plan a refactor from the code and tests already in the repo. Add a workspace ### Bring project tools along. * Everything in the profile * Your configured issue tracker * Your configured error or analytics tools For example: use a connected tracker and error service to investigate a reported bug. Add your provider’s MCP endpoints and authenticate them first. Agent-defined connections and native global tools can also apply. [Build a workspace configuration](https://getagentfarm.com/configuration#workspace) [Next / Configuration **See what goes into a setup.**](https://getagentfarm.com/configuration) --- Agent Farm / Field notes 02 # Plain files. Your choices. Your library lives in ~/.config/agent-farm/. The interactive CLI creates the files for you; open them whenever you want to tune a setup. Start with a name ## A profile points to an agent. A profile is the entry point you select in the picker or pass to `agent-farm run`. Its YAML names the agent. Model settings, skills, and instructions belong in the agent file. profiles/planner.yaml ``` agent : planner ``` Inside an agent.md file ## Define the worker. This annotated example follows the [bundled planner](https://github.com/dcouple/agent-farm/blob/main/plugins/dcouple/agents/planner.md) . Save agent definitions as Markdown; the filename is their identifier. Use a model your installed harness and account support. agents/planner.md ``` --- harness : claude # Native CLI to launch model : name : claude-fable-5-1 # Model selected by this agent reasoning : high # Thinking effort skills : - create-ticket # Shared skill directory names - explain-visually description : Discuss intent and create actionable tickets and briefs. subagents : socrates : # Name the parent uses to delegate agent : socrates # Another file: agents/socrates.md mode : native # Delegate through the same harness --- You are the issue-creation identity using dcouple/skills. Use the bundled create-ticket skill to discuss work, preserve intent, and create or update GitHub issues and Grain briefs when authorized by the user. Follow its Socrates review and finalization gates. Begin with the user's request. Keep this session focused on discussing intent and creating tickets. ``` harness `claude` or `codex`: the native CLI that executes the work. model The model name and reasoning effort for this agent. Availability depends on your native harness and account. skills Directory names from your shared `skills/` library. Each contains a `SKILL.md` playbook. description A short description of the agent’s job. subagents Explicit bindings to other agent files. Each needs a `mode`: `native` uses harness delegation; `process` launches a separate configuration and supports cross-harness children. Markdown body The instructions the agent follows. Optional `instructions_files` can prepend shared instructions. Install the bundled plugin with `agent-farm init` to get this planner’s referenced skills and Socrates child. Native child declarations support one level. See the [full configuration reference](https://github.com/dcouple/agent-farm/blob/main/CONFIGURATION.md) for supported fields and formats. Add project connections ## A toolbox you can take along. Replace the example URL with your provider’s real MCP endpoint. `auth: native` keeps sign-in in Claude Code or Codex; the optional description tells your agent what the connection is for. workspaces/my-project.yaml ``` instructions : | Use the project associated with this workspace. connections : project-tools : type : mcp url : https://YOUR-MCP-SERVER.example/mcp auth : native description : Query the tools for this project. ``` Sign in, then launch ``` agent-farm mcp login project-tools --workspace my-project --harness claude agent-farm run planner --workspace my-project ``` Your native harness stores credentials. Connect local stdio servers with `command` and `args`, and inherit environment variables by name through `env_vars`. [Read the local server examples.](https://github.com/dcouple/agent-farm/blob/main/CONFIGURATION.md#local-mcp-servers-and-native-sign-in) Check your setup ## See what will be loaded. Inspect and diagnose ``` agent-farm inspect planner --workspace my-project agent-farm doctor ``` `inspect` shows the resolved graph, settings, and source paths. Check live connections in your native harness’s MCP view. Across repositories ## Keep useful skills close. Install a profile’s top-level skills into your native user skill directory for use across repositories. Load, check, and remove managed skills ``` agent-farm set global planner --harness claude agent-farm status global --harness claude agent-farm unset global planner --harness claude ``` Unloading removes managed skill links while retaining the source files. [Read how native skill layouts are generated.](https://github.com/dcouple/agent-farm/blob/main/CONFIGURATION.md#source-files-versus-native-output) Share a library ## Package your setups. Plugins distribute versioned profiles, agents, skills, and supporting resources. Update the bundled configuration after updating your CLI checkout. Updates flag conflicts with local edits. Install the bundled configuration ``` agent-farm plugin install ``` For a custom source, use `agent-farm plugin validate /path/to/config` before `agent-farm plugin install /path/to/config`. For scripted work ## Run from a script. Use `--exec` with a starting message for a headless run. Run a task headlessly ``` agent-farm run implementer --exec \ --message "Fix the failing tests" ``` Launch defaults: Claude `--dangerously-skip-permissions`; Codex `--yolo`. Review the [launch permissions](https://github.com/dcouple/agent-farm/blob/main/docs/operations.md) before automating a task. [Next / Find your fit **Where Agent Farm fits.**](https://getagentfarm.com/compare) --- Agent Farm / Field notes 03 # Keep the workflow you like. Agent Farm is for switching repeatable setups while staying in Claude Code or Codex. Start with the part of your workflow you want to change. Find your fit ## Three ways to set up work. Choose the approach that fits your workflow. Native configuration, Agent Farm, and Omnigent | Approach | What you manage | Where you work | A good fit when… | | --- | --- | --- | --- | | Native configuration | Each harness’s own settings, instructions, and tools. | The native Claude Code or Codex interface. | You prefer to configure each harness directly. | | Agent Farm Your setups, saved | Named profiles, shared skills, child definitions, and workspace connections. | The native Claude Code or Codex terminal, launched with a generated configuration. | You switch roles or projects and want reusable setups. | | Omnigent | Agents and persistent, shareable sessions through Omnigent. | Omnigent’s interface for its Claude Code and Codex integrations, with connected web, mobile, and desktop interfaces. | You want a shared session experience across interfaces. | Based on the [Agent Farm README](https://github.com/dcouple/agent-farm#how-it-works) and [Omnigent terminal documentation](https://omnigent.ai/docs/interact/terminal) , reviewed September 16, 2026. Interfaces and supported integrations can change. What Agent Farm owns ## Configuration, then launch. Agent Farm combines your agent definition, selected skills, children, and optional workspace connections into a launch bundle. Claude Code or Codex executes the agent turns and supplies the native tools. **Agent Farm** Assemble your setup **Claude Code / Codex** Run the work Separate bundles let you launch different configurations in one repository. Use separate worktrees for independent code changes. [Read the operational notes.](https://github.com/dcouple/agent-farm/blob/main/docs/operations.md) A sibling project ## Need room for parallel work? [Pane](https://runpane.com/) manages visible agent workspaces and terminals. Agent Farm manages the setup you bring to a session. Explore Pane when you want to organize multiple pieces of work side by side. [Next / Keep exploring **Go straight to the source.**](https://getagentfarm.com/resources) --- Agent Farm / Field notes 04 # Keep exploring. The code, the playbooks, and the details behind your setup. A few useful places to go next. * [ Build & contribute ## Agent Farm on GitHub Source code, installation instructions, issues, and the product overview. ](https://github.com/dcouple/agent-farm) * [ Reference ## Documentation File formats, agent definitions, child bindings, native skill layouts, and MCP connections. ](https://getagentfarm.com/docs) * [ The writeup ## Why Agent Farm A setup for each kind of work, with shared playbooks and your native terminal. ](https://getagentfarm.com/docs/why-agent-farm) * [ Playbooks ## Skills & profile sources The shared workflows and configuration behind the bundled dcouple plugin. ](https://github.com/dcouple/skills) * [ Practical details ## Operational notes Launch permissions, authentication, generated files, and current limitations. ](https://github.com/dcouple/agent-farm/blob/main/docs/operations.md) * [ Learn by reading ## Bundled agents Real planner, implementer, reviewer, and other definitions to inspect and adapt. ](https://github.com/dcouple/agent-farm/tree/main/plugins/dcouple/agents) * [ Evidence ## Verification history Recorded component tests and native launch checks, with their verification boundaries. ](https://github.com/dcouple/agent-farm/blob/main/docs/verification-history.md) * [ Sibling project ## Pane A home for parallel agent workspaces, terminals, and your Git workflow. ](https://runpane.com/) [Ready when you are **Start your first session.**](https://getagentfarm.com/#get-started) --- # Agent Farm documentation Think of Agent Farm as a set of toolboxes for your AI assistant. You might keep one for SEO, another for presentations, and another for coding. For each job, you choose the AI model, give it useful background, and pick the tools it needs. You also give it **skills**: step-by-step workflows, like researching a topic or turning an outline into slides. Agent Farm saves those choices so you can pick a setup by name and start working in Claude Code or Codex. Your toolbox is ready whenever you need it. ## Start here 1. [Install Agent Farm](https://getagentfarm.com/docs/getting-started) and launch your first session. 2. [Create a profile](https://getagentfarm.com/docs/profiles) with the model and instructions you want. 3. [Add skills](https://getagentfarm.com/docs/skills) for the work you do often. 4. [Connect a workspace](https://getagentfarm.com/docs/workspaces) for project tools. For the thinking behind the product, read [Why Agent Farm](https://getagentfarm.com/docs/why-agent-farm). ## The building blocks Imagine bringing someone in to help with your business. You would tell them what job they have, show them how you like the work done, and give them the material they need. Setting up an AI assistant follows the same pattern. ### An agent gives the worker a job Someone researching a market needs different guidance from someone building a presentation. An **agent definition** records those choices: which AI app and model to use, what instructions to follow, and which skills and helpers to bring along. You can give each role a setup suited to its work. ### A skill explains how to do the work Giving someone access to email lets them send a message. They still need a process: understand the recipient, check the facts, draft the message, review it, and send it when approved. A **skill** is that repeatable workflow, written down for the agent. Tools provide the individual actions; the skill explains how to use them together. When you improve the process, every agent using that skill can benefit. ### A profile makes the setup easy to choose Once you have a setup you like, give it a name. A **profile** points to an agent definition, so choosing `planner` brings back your planning setup. You can switch jobs and return later with the same choices ready. ### A workspace brings in the project The same presentation specialist might work for two companies. Each has its own brand guidance, background material, and tools. A **workspace** supplies project instructions and tool connections separately from the agent’s role. You can bring the same way of working to a different project. ### A plugin shares what works Once you have useful agents and workflows, a teammate may want to use them too. A **plugin** packages profiles, agent definitions, and skills together so they can install the setup and build on it. The bundled plugin gives you a starting set to try and adapt. ## Pick your next step - [CLI reference](https://getagentfarm.com/docs/cli): commands, flags, and examples. - [Child agents](https://getagentfarm.com/docs/delegation): native and process delegation. - [Plugins](https://getagentfarm.com/docs/plugins): install and share configurations. - [Troubleshooting](https://getagentfarm.com/docs/troubleshooting): diagnose setup and connection issues. - [For AI tools](https://getagentfarm.com/docs/ai-tools): Markdown pages and a complete text export. ## Source and scope These guides are adapted from the [Agent Farm repository](https://github.com/dcouple/agent-farm). Each technical guide links to its source. Commands describe the documented launcher reviewed on September 16, 2026. --- # Get started ## Prerequisites - macOS or Linux. - Node.js 22.15 or later. - pnpm and Git. - Claude Code or Codex installed and authenticated. Use a repository you are comfortable giving your agent access to. Current launches enable Claude’s `--dangerously-skip-permissions` or Codex’s `--yolo` by default. See [launch permissions](https://getagentfarm.com/docs/troubleshooting#launch-permissions) for details. ## Install from source ```sh git clone https://github.com/dcouple/agent-farm.git cd agent-farm pnpm install --frozen-lockfile && pnpm build mkdir -p ~/.local/bin ln -s "$PWD/dist/cli.js" ~/.local/bin/agent-farm ``` Keep the checkout: the command links to its built CLI. Add `~/.local/bin` to your shell’s `PATH`: ```sh export PATH="$HOME/.local/bin:$PATH" ``` Put that export in your shell configuration, such as `~/.zshrc`, to keep it in future terminals. ## Initialize your library ```sh agent-farm init ``` The walkthrough checks prerequisites, installs the default plugin’s profiles and skills, and offers to launch your first session. Your configuration library lives in `~/.config/agent-farm/`. ## Launch a session ```sh cd ~/repos/my-app agent-farm ``` Choose a profile, optionally select a workspace, and confirm the repository. Agent Farm prepares a bundle under `.agent-farm/generated/` and opens the chosen native CLI. From your project folder, you can launch a known profile directly: ```sh agent-farm run planner ``` Use your repository’s `.gitignore` to exclude `.agent-farm/generated/` from version control. Keep bundles used by active sessions. ## Check your setup ```sh agent-farm profiles list agent-farm doctor agent-farm help run ``` Next, [learn how profiles select agents](https://getagentfarm.com/docs/profiles) or [connect project tools](https://getagentfarm.com/docs/workspaces). Source: [Installation and entry points](https://github.com/dcouple/agent-farm/blob/main/README.md). --- # Why Agent Farm You want an agent to help with SEO. You choose a model, give it background on your site, and connect your search data. A skill walks it through the work: research what people search for, improve a page, and review the result. Later, you need a presentation. Your agent needs brand guidelines, slide tools, and a workflow for turning an idea into a clear story. For email, it needs to understand the audience, follow your writing style, and work through drafting, review, and sending. Tools let the agent take actions. Skills bring those actions together into a repeatable workflow. References give it background. Each job calls for a different mix. Loading every workflow and reference into every session makes more instructions compete for the agent’s attention. A focused setup gives it the context that matters for the work at hand. Agent Farm lets you save those choices. Pick the setup for the job and get to work. ## Give the job a name A profile such as `planner` selects an agent definition. That definition holds the harness, model, thinking effort, skills, and instructions for the job. ```sh agent-farm run planner agent-farm run implementer ``` The name is a small promise: this is the setup you chose for this kind of work. You can inspect and edit it in plain files. ## Keep the playbooks together A skill captures a workflow you want to repeat: investigate a bug, preserve intent in a ticket, or review a change. Agent definitions select skills from a shared library. That gives you a place to improve the workflow and a choice about which agents use it. ## Bring the project’s tools The worker and the project are separate choices. A workspace adds the project’s instructions and MCP connections to a launch. ```sh agent-farm run planner --workspace my-project ``` For a connected project, a planning session can use an issue tracker alongside the repository. For another project, choose a different workspace while keeping the same planner. ## Keep your native terminal Agent Farm assembles a launch bundle. Claude Code or Codex runs the conversation and provides the tools you use to do the work. Your repository keeps its own instructions and references. Your native harness handles authentication. You keep editing the setup as your work changes. ## Start small Start with the bundled profiles. Run a real task. When you find instructions or a playbook worth repeating, save them in the library. [Launch your first session](https://getagentfarm.com/docs/getting-started), then [make the setup yours](https://getagentfarm.com/docs/profiles). Further reading: [Agent Farm overview](https://github.com/dcouple/agent-farm/blob/main/README.md) and [configuration reference](https://github.com/dcouple/agent-farm/blob/main/CONFIGURATION.md). --- # Profiles and agents A profile is a launchable name. It points to an agent definition in your configuration library. ## Library layout ```text ~/.config/agent-farm/ ├── profiles/ │ └── planner.yaml ├── agents/ │ └── planner.md ├── skills/ │ └── create-ticket/ │ └── SKILL.md └── workspaces/ └── my-project.yaml ``` Run `agent-farm` to create a profile interactively, or edit the files directly. ## Name the profile Create `profiles/planner.yaml`: ```yaml agent: planner ``` The profile selects the full identity from `agents/planner.md`. Settings belong in that agent file. ## Define the agent This example follows the bundled Claude planner. Its referenced skills and child agent are installed by `agent-farm init`. ```yaml filename="agents/planner.md" --- harness: claude model: name: claude-fable-5-1 reasoning: high skills: - create-ticket - explain-visually description: Discuss intent and create actionable tickets and briefs. subagents: socrates: agent: socrates mode: native --- Discuss the user's intent and create actionable tickets. Use the create-ticket workflow and its Socrates review. Begin with the user's request. ``` Use a model available to your account and installed harness. | Field | Purpose | | --- | --- | | `harness` | `claude` or `codex`, the native CLI to launch. | | `model.name` | The model identifier. | | `model.reasoning` | The reasoning effort supported by the selected model and harness. | | `skills` | Directory names in the shared skills library. | | `description` | A short description of the agent’s work. | | `subagents` | Explicit child bindings, each with an `agent` and `mode`. | | Markdown body | Instructions for the agent. | | `instructions_files` | Optional shared instruction files to prepend. | The filename gives the agent its identifier. An agent can be a profile’s entry point, a child, or both. ## Inspect and launch ```sh agent-farm profiles list agent-farm inspect planner agent-farm run planner ``` `inspect` returns the resolved configuration graph and source paths. Add `--workspace my-project` to preview project connections too. ## Repository context Your repository’s `AGENTS.md`, `CLAUDE.md`, and references stay repository-owned. Agent Farm writes the launch bundle into `.agent-farm/generated/` in that repository. Read [Skills](https://getagentfarm.com/docs/skills) and [Child agents](https://getagentfarm.com/docs/delegation) to extend the definition. Sources: [Configuration reference](https://github.com/dcouple/agent-farm/blob/main/CONFIGURATION.md#agents) and [bundled planner](https://github.com/dcouple/agent-farm/blob/main/plugins/dcouple/agents/planner.md). --- # Skills A skill is a reusable workflow with a name, a description, and instructions. Agents select skills by their directory names. ## Write a playbook Create `~/.config/agent-farm/skills/review-change/SKILL.md`: ```md --- name: review-change description: Review a code change and report actionable findings. --- Read the task and diff. Trace the affected behavior. Run the relevant checks. Report findings with file references, expected behavior, and evidence. ``` Add it to an agent definition: ```yaml skills: - review-change ``` ## Keep supporting material nearby ```text skills/review-change/ ├── SKILL.md ├── references/ │ └── review-rubric.md └── metadata/ └── codex.yaml ``` Use `references/` for supporting guidance. Keep executable helpers and assets in suitable directories alongside the skill. For Codex presentation and invocation policy, `metadata/codex.yaml` can contain: ```yaml interface: display_name: Review Change short_description: Review code with actionable evidence default_prompt: Use $review-change to review this diff. policy: allow_implicit_invocation: true ``` ## Native layouts Agent Farm preserves `SKILL.md` and supporting files. For Codex it translates `metadata/codex.yaml` to the native `agents/openai.yaml` path. Claude’s generated layout uses the skill and its supporting resources. Keep one metadata filename per skill. Imported skills using the native `agents/openai.yaml` filename remain supported. ## Use skills across repositories ```sh agent-farm set global planner --harness claude agent-farm status global --harness claude agent-farm unset global planner --harness claude ``` `set global PROFILE` installs that profile’s selected top-level skills into the native user skill directory. To launch its model, instructions, and children together, use `agent-farm run PROFILE`. `status global` shows managed, pre-existing, and changed skills. Unloading removes owned links and preserves source files. User-level layouts live under `~/.cache/agent-farm/user-skill-layouts/` and link to central sources. Existing file edits remain live. After adding, removing, or renaming files, unload every profile sharing that skill and load them again. Source: [Skill authoring and native output](https://github.com/dcouple/agent-farm/blob/main/CONFIGURATION.md#skills). --- # Workspaces and MCP A workspace holds a project’s tool connections and shared guidance. Choose it independently of the repository folder and agent profile. ## Connect a remote server Create `~/.config/agent-farm/workspaces/my-project.yaml`: ```yaml instructions: | Use the project associated with this workspace. Keep operations within the user's requested scope. connections: project-tools: type: mcp url: https://YOUR-MCP-SERVER.example/mcp auth: native description: | Query tools for this project. Select the project before running queries. ``` Replace the example URL with your provider’s MCP endpoint. The description gives the agent context about the service and project selection. ## Authenticate and launch For the Claude planner: ```sh agent-farm mcp login project-tools --workspace my-project --harness claude agent-farm run planner --workspace my-project ``` For Codex, use `--harness codex` during login and a Codex profile such as `astra-planner` at launch. The native client opens its sign-in flow and stores credentials. Claude and Codex each maintain their own credentials. Stable connection names and URLs support reuse across repositories; changing either can require a fresh login. ## Connect a local server A connection can launch a local stdio process: ```yaml connections: local-service: type: mcp command: example-mcp-server args: [serve] env: PROJECT_ID: example-project env_vars: [EXAMPLE_API_TOKEN] ``` Use your server’s actual command. It must be on `PATH` or use an absolute path. The process runs in your selected repository. - `args` passes arguments as an array. - `env` holds literal, non-secret settings. - `env_vars` lists variables inherited at launch, keeping secret values in the environment. Use the service’s own authentication flow for local servers. ## Check the connection ```sh agent-farm inspect planner --workspace my-project ``` This shows configured endpoints and source files. Check live connectivity in the native harness’s MCP view. Workspace instructions are prepended to agent instructions. Connection descriptions become a Workspace tools section. Service permissions remain enforced by the provider; project guidance supplies prompt context. ## Install a workspace globally ```sh agent-farm set global --workspace my-project --harness codex agent-farm status global agent-farm unset global --workspace my-project --harness codex ``` Each harness has one global workspace slot. The install includes the workspace’s connections, instructions, and descriptions. Profile and model settings stay under the agent definition. Agent Farm tracks ownership and checks for conflicts before writing. Start fresh native sessions to pick up changes. On scoped `agent-farm run` launches, explicitly select `--workspace` for the tools you want. Source: [Workspaces, sign-in, and global installation](https://github.com/dcouple/agent-farm/blob/main/CONFIGURATION.md#workspaces-and-repositories). --- # Child agents An agent can declare other agents it may delegate to. Every binding names an agent file and chooses a delegation mode. ## Native delegation The bundled planner binds its Socrates reviewer this way: ```yaml subagents: socrates: agent: socrates mode: native ``` The parent delegates through its native harness. The child’s definition lives in `agents/socrates.md`. Native child declarations support one level. Claude native children inherit the parent’s connections. Harness capabilities determine the native delegation behavior. ## Process delegation Use process mode to launch a separately generated configuration, including for cross-harness children: ```yaml subagents: worker: agent: worker mode: process ``` The bundled `worker` is a Codex agent. Its definition illustrates a worker with its own model and skill selection: ```yaml --- harness: codex model: name: gpt-5.6-luna reasoning: max description: Implement assigned work and return verification evidence. skills: - implementer --- Implement the assigned task, run relevant checks, and report evidence. Return remaining questions to the parent. ``` Choose a model available to your harness and account. Process children receive their own generated configuration. ## Keep instructions and identities distinct A document under a skill’s `references/` directory is supporting guidance. A child agent is an identity under `agents/`, selected through an explicit binding. Inspect the parent graph before launching: ```sh agent-farm inspect planner --workspace my-project ``` Use separate worktrees when parent and child work should make independent code changes. Generated bundles share access to the repository, credentials, and native global configuration. Sources: [Agent definitions](https://github.com/dcouple/agent-farm/blob/main/CONFIGURATION.md#agents), [child behavior](https://github.com/dcouple/agent-farm/blob/main/docs/operations.md#child-agents), and [bundled worker](https://github.com/dcouple/agent-farm/blob/main/plugins/dcouple/agents/worker.md). --- # Plugins A plugin packages versioned profiles, agents, skills, and supporting resources. Agent Farm includes a `dcouple` plugin to start your library. ## Install or update the bundled plugin ```sh agent-farm plugin install ``` `agent-farm init` installs the bundled plugin during first-time setup. After updating your CLI checkout, run `plugin install` to apply its configuration updates. CLI and plugin versions are independent. Updates check local modifications and report conflicts for you to resolve. ## Install a custom source ```sh agent-farm plugin validate /path/to/config agent-farm plugin install /path/to/config ``` Validation checks that profiles resolve, skills exist, and agent definitions parse. Keep credentials and project workspace connections local. ## Authoring workflow The bundled configuration is authored in [dcouple/skills](https://github.com/dcouple/skills). Its publishing workflow validates the configuration and proposes an updated snapshot under `plugins/dcouple/` in the Agent Farm repository. Start from the [bundled package](https://github.com/dcouple/agent-farm/tree/main/plugins/dcouple) when exploring the file structure and manifest. Plugins distribute configuration and resources. Sources: [CLI commands](https://github.com/dcouple/agent-farm/blob/main/src/commands.ts) and [plugin operations](https://github.com/dcouple/agent-farm/blob/main/docs/operations.md#plugin-rollout). --- # CLI reference Use `agent-farm help` to see the commands supported by your installed version. Add a command name for its flags and examples: ```sh agent-farm help run ``` ## Setup and discovery | Command | Purpose | | --- | --- | | `agent-farm init` | Check prerequisites, install defaults, and walk through setup. | | `agent-farm init --full` | Display the setup content together. | | `agent-farm` | Open the interactive profile picker and configuration flow. | | `agent-farm profiles list` | List profiles with resolved agents, harnesses, and models. | | `agent-farm doctor` | Check prerequisites, configuration, profiles, workspaces, and skills. | | `agent-farm help [COMMAND]` | Show the command reference. | ## Launch a profile ```sh agent-farm run NAME [options] ``` | Flag | Value | Behavior | | --- | --- | --- | | `--directory` | Repository path | Work in this directory; defaults to the current directory. | | `--workspace` | Workspace name | Add the workspace’s project connections. | | `--message` | Quoted text | Supply an initial task. | | `--exec` | Boolean | Execute headlessly. | | `--build` | Boolean | Generate a bundle and print its path. | | `--explain` | Boolean | Print the resolved launch command as JSON. | | `--config-root` | Library path | Use a configuration library; defaults to `~/.config/agent-farm`. | `--build` and `--explain` are preparation modes. Use the plain command to launch a session. ```sh agent-farm run planner --directory ~/repos/my-app agent-farm run implementer --workspace my-project --message "Fix the failing tests" agent-farm run planner --workspace my-project --explain ``` ### Headless execution ```sh agent-farm run implementer --exec \ --message "Fix the failing tests" ``` The native harness runs the task. Review [launch permissions](https://getagentfarm.com/docs/troubleshooting#launch-permissions) before automation. ## Inspect a setup ```sh agent-farm inspect NAME --workspace WORKSPACE ``` The JSON result includes the resolved graph, model settings, skills, children, configured endpoints, and source paths. Use the native MCP view to verify a live connection. ## Manage global skills ```sh agent-farm set global PROFILE --harness claude agent-farm status global --harness claude agent-farm unset global PROFILE --harness claude ``` These commands manage top-level skill links. Use `codex` to target Codex instead. See [Skills](https://getagentfarm.com/docs/skills). ## Manage a global workspace ```sh agent-farm set global --workspace my-project --harness codex agent-farm status global agent-farm unset global --workspace my-project --harness codex ``` See [Workspaces](https://getagentfarm.com/docs/workspaces#install-a-workspace-globally) for ownership and session behavior. ## Authenticate a remote connection ```sh agent-farm mcp login CONNECTION --workspace WORKSPACE --harness claude ``` Use the matching connection name from your workspace. Authenticate separately for each harness you use. ## Manage plugins ```sh agent-farm plugin install agent-farm plugin validate /path/to/config agent-farm plugin install /path/to/config ``` Source: [Command definitions](https://github.com/dcouple/agent-farm/blob/main/src/commands.ts). Consult your installed CLI’s help when versions differ. --- # Troubleshooting Start with the built-in diagnostic and the profile you intend to run: ```sh agent-farm doctor agent-farm inspect planner ``` ## Find the command Check the installation path and native prerequisites: ```sh command -v agent-farm node --version command -v claude command -v codex ``` Use Node.js 22.15 or later. Add `~/.local/bin` to `PATH` and keep the Agent Farm source checkout that your symlink points to. Install and authenticate the native harness selected by your profile. ## Resolve a profile or skill ```sh agent-farm profiles list agent-farm inspect planner ``` Check that the profile names an agent file and that each selected skill directory contains `SKILL.md`. Every child binding needs an explicit `native` or `process` mode. After updating the CLI checkout, use `agent-farm plugin install` to apply the bundled configuration. Resolve any reported local-edit conflicts deliberately. ## Reconnect a workspace tool ```sh agent-farm inspect planner --workspace my-project agent-farm mcp login project-tools --workspace my-project --harness claude ``` Replace `project-tools` with your connection name. Complete the native browser sign-in, then launch with the workspace selected. Check the harness’s MCP view for connectivity. Claude and Codex have separate credentials. Endpoint or connection-name changes, revoked access, and provider policies can require a new sign-in. Local stdio services use their own login flow. ## Refresh global configuration Start a fresh native session after changing a global workspace or skill install. Project settings can take precedence over global settings. Agent Farm records global workspace ownership under `~/.local/state/agent-farm/user-workspaces/state.json`. Keep that registry through unloading. Changed managed entries need reconciliation before unload can complete. For skill file additions, removals, or metadata renames, unload all profiles sharing that skill and load them again. ## Launch permissions Current launches use these native flags by default, including headless runs and generated process children: | Harness | Flag | Effect | | --- | --- | --- | | Claude Code | `--dangerously-skip-permissions` | Runs with permission checks bypassed. | | Codex | `--yolo` | Runs with approval prompts and sandboxing bypassed. | Choose the repository and task scope accordingly. Agent Farm generates these launch settings per session; native global permission settings stay as configured. ## Generated files and parallel work Bundles live in `.agent-farm/generated/` in the target repository. Keep bundles needed by running sessions and exclude the directory from Git. Bundles share filesystem access, credentials, and native global configuration. Use separate worktrees for independent code changes. ## Gather a useful report Include the command, selected harness, operating system, configuration error, and relevant diagnostic output. Redact credentials and private endpoints before sharing. [Open an Agent Farm issue](https://github.com/dcouple/agent-farm/issues/new). Sources: [Operational notes](https://github.com/dcouple/agent-farm/blob/main/docs/operations.md) and [configuration reference](https://github.com/dcouple/agent-farm/blob/main/CONFIGURATION.md). --- # For AI tools Every public page is available as rendered HTML and plain Markdown. The documentation uses its original Markdown source; product and field guides are converted from the built page. ## Choose a format | Format | URL | Use | | --- | --- | --- | | Site index | [/llms.txt](https://getagentfarm.com/llms.txt) | Find page summaries and Markdown URLs. | | Complete site | [/llms-full.txt](https://getagentfarm.com/llms-full.txt) | Load every public page in one text file. | | Individual Markdown | [/docs/raw/getting-started.md](https://getagentfarm.com/docs/raw/getting-started.md) | Read a single guide. | | Landing page Markdown | [/raw/index.md](https://getagentfarm.com/raw/index.md) | Read the product overview. | | Sitemap | [/sitemap.xml](https://getagentfarm.com/sitemap.xml) | Discover canonical HTML pages. | Every HTML page declares its Markdown alternate in its metadata. Documentation pages also link to Markdown and include a **Copy page** action. Use the page heading links to cite a specific section. ## Read from the terminal ```sh curl -fsSL https://getagentfarm.com/llms.txt curl -fsSL https://getagentfarm.com/docs/raw/cli.md ``` When previewing locally, use `http://localhost:3000` as the origin. ## Use the right context Start with the index and load the guides relevant to the task. The [CLI reference](https://getagentfarm.com/docs/cli), [profile format](https://getagentfarm.com/docs/profiles), and [workspace guide](https://getagentfarm.com/docs/workspaces) cover most configuration work. These documents explain product behavior. Follow the user’s requested scope and the repository’s own instructions when applying them. Check `agent-farm help` for the installed CLI’s current commands. ## Sources and freshness Technical guides link to the Agent Farm repository. The documentation source snapshot is recorded in this website’s `docs/content-sources.json`. HTML, Markdown exports, search, and the sitemap are produced from checked-in content during the build. All 16 public pages are listed in the sitemap and AI index. Main content is included in the initial HTML, and `robots.txt` allows crawlers.