Agent Farm

Load the right skills for each job. Keep your native terminal.

Agent Farm is a harness configurator. A harness is the full working setup around an AI model — instructions, tools, permissions, and checks. Agent Farm lets you save different setups and switch between them without reinstalling everything for every conversation.

Pick a setup, point it at a repo, and Agent Farm opens your native Claude Code or Codex terminal with that configuration loaded.

Think of each setup as a desk prepared for a job. For SEO, you might lay out site references, search tools, and a skill that walks through researching and improving a page. For presentations, you bring brand guidelines, slide tools, and a workflow for turning an outline into a story. Each setup keeps the relevant material close to the work.

Install

Requires Node 22.15+ on macOS, Linux, or Windows, and the Claude Code and/or Codex CLI installed and authenticated. On Windows, turn on Developer Mode (Settings > System > For developers) before launching Codex profiles or running agent-farm set global, because those link individual files.

npm install --global @greenfieldco/agent-farm
agent-farm init
agent-farm plugin install orchestra    # optional: the overseer profile below
agent-farm plugin install bigbrain     # optional: the one-front-door workflow below
agent-farm plugin install machine-security  # optional: audit and harden this Mac or PC

agent-farm init checks your prerequisites, installs the default greenfield plugin (its profiles and skills), explains how everything fits together, and offers to launch your first session. The orchestra, bigbrain and machine-security plugins ship in the same package but are installed only when you ask for them. After upgrading Agent Farm, rerun agent-farm plugin install and agent-farm plugin install NAME for each plugin you use, to pick up new profiles.

Launched agents run without permission prompts (Claude --dangerously-skip-permissions, Codex --yolo). Read docs/operations.md before pointing one at a repository you care about.

To work on Agent Farm itself, see docs/development.md.

Profiles

Agent Farm ships with profiles ready to use. With greenfield and orchestra installed, agent-farm shows a menu like this (abridged):

◆  What would you like to do? Tab: show all descriptions
│  ● greenfield/planner (2) (Help you understand a problem, decide what to do, and write the plan. Doesn't write code.)
│  ○ orchestra/overseer (2)
│  ○ greenfield/implementer (4)
│  ○ greenfield/qa-and-fix (2)
│  ○ greenfield/reviewer (2)
│  ─────────────────────
│  + Create new profile

Highlight a profile to see what it's for, or press Tab to show every profile's description at once.

Plan — greenfield/planner helps you understand a problem, decide what to do, and write the plan. Start here.

Build — greenfield/implementer is the AI model on its own plus a few good habits: it builds a plan or a clear task into a pull request and watches it until checks are green. orchestra/overseer builds, tests, and reviews a task into a pull request with little hand-holding.

Check — greenfield/reviewer reviews a pull request from many angles at once. greenfield/qa-and-fix tests a finished pull request, fixes small safe problems, and tells you when it's ready. greenfield/simplify-and-refactor asks whether an open pull request could be simpler and applies only the cleanup you approve.

More (all in greenfield) — product-researcher for research write-ups, business for business documents, seo for search content, audits for finding outdated issues and docs, code-smell-fixes for an unattended whole-codebase hunt for confusing code that ends in fix PRs and issues, ui-polish for exploring a running app, fixing its hover, focus and layout rough edges, and showing before and after screenshots, and customer-insights-loop for turning a product's own usage data into ranked directions, then building the ones you pick and handing back every PR together.

These profiles used to live in the dcouple plugin, which still ships for existing installs. dcouple/raw became greenfield/implementer; dcouple/ideate and dcouple/implementer were not moved. An installed dcouple keeps working until you run agent-farm plugin uninstall dcouple.

bigbrain — An opt-in alternative to greenfield (agent-farm plugin install bigbrain): you talk only to bigbrain/orchestrator, which relays every worker's questions to you, every plan carries a control flow the implementer runs step by step, reviews happen only at planned points or on your word, and every document passes a bundled checker. See plugins/bigbrain/README.md.

machine-security — machine-security/audit scans the Mac or Windows PC you're working on (updates, disk encryption, antivirus and firewall, sharing and remote access, startup persistence, secrets on disk, SSH keys, package-manager and agent settings, MCP servers), reports what to fix first, and applies only the fixes you approve, one command at a time. The scans are read-only, never use sudo or elevation, and never print a secret value. See plugins/machine-security/README.md.

Guides — The workflow plugins each have a one-page visual guide to their profiles and how work is routed: greenfield, orchestra, bigbrain, and dcouple. They're also on Grain: greenfield, orchestra, and dcouple.

Variants — Some profiles come in more than one version, such as a Claude and a Codex planner. They're one profile with variants, and the menu shows how many: greenfield/planner (2), and asks which one you want. agent-farm run never asks: without a variant name it launches the profile's default and prints the commands for the others. Add the variant name to run another, as in greenfield/planner:codex. If a variant fails to start, the error names the other variants to try. agent-farm profiles list shows every variant with its model. Resuming with --resume ID reopens the variant that started the session, and Pane uses it to restore panels (details).

Four entry points

agent-farm init         # First-time setup — the starting point
agent-farm              # Interactive — pick a profile, create one, launch
agent-farm help         # Reference — every command, for humans and agents
agent-farm doctor       # Diagnostic — check prerequisites, config, profiles

agent-farm init is where you start, and agent-farm runs it for you on first launch. After that, agent-farm is your everyday launcher. agent-farm help is the single discovery point for all commands. agent-farm doctor tells you what's working and what's not.

For power users

agent-farm run greenfield/planner
agent-farm run greenfield/planner:codex
agent-farm run greenfield/implementer --directory ~/repos/my-project --message "Fix the failing tests"
agent-farm run greenfield/implementer:sol
agent-farm run greenfield/reviewer:codex --message "Review PR #42"

Several plugins can be installed together. Use plugin/profile when plugins publish the same name: both dcouple and greenfield have an implementer, so with both installed agent-farm run implementer stops and asks you to qualify it. Setting "default_plugin": "greenfield" in settings.json makes bare names prefer that plugin.

--arg values are declared by each agent; agent-farm inspect PROFILE lists them. Run agent-farm help run for all flags.

Dashboard

agent-farm ui opens a local browser dashboard with Sessions and Profiles. Sessions shows each run's user turns, sub-agents, timeline, token usage, and reported cost. Profiles lets you create and edit local presets and duplicate read-only plugin profiles. It opens a browser, not an agent session.

How it works

Choose a profile to select an agent's harness, model, and instructions. Agent Farm combines that definition with shared skills, child agent definitions, and optional workspace MCP connections into a launch bundle in .agent-farm/generated/ under the launch directory, then opens Claude Code or Codex to work there. Add .agent-farm/generated/ to your repository's .gitignore.

• Profile — a saved setup. "When I say planner, I mean: use this agent, optionally with these model fields and launch arguments." Like choosing which worker to send.
• Agent — the worker definition. Which AI brain, what it knows, what instructions it follows, who it can delegate to.
• Skill — a playbook. Step-by-step instructions for a kind of task: how to create a ticket, review code, or investigate a bug.
• Workspace — the toolbox for a project. Which external tools (Linear, Sentry, databases) an agent can reach when working on that project.

Configuration

Personal configuration lives in ~/.config/agent-farm/; every command accepts --config-root DIR to use another directory. Project connections and instructions live in a tracked .agent-farm/workspace.yaml at the repository root, which you approve once with agent-farm workspace trust. Keep secrets out of these files: connections name environment variables instead of holding values.

agent-farm plugin install                 # bundled greenfield
agent-farm plugin install orchestra
agent-farm plugin install bigbrain
agent-farm plugin install machine-security
agent-farm plugin install /path/to/plugin
agent-farm plugin list
agent-farm profiles list
agent-farm workspace trust                # approve this repository's workspace file
agent-farm run greenfield/implementer --explain   # show the resolved launch without starting it

Sessions record local OpenTelemetry data under ~/.local/state/agent-farm/telemetry/; nothing is sent anywhere. Conversation text is recorded only if you set telemetry.capture_content: true. To route third-party models through a gateway such as OpenRouter, use agent-farm provider set (details).

The configuration reference covers profiles, agents, skills, plugins, workspaces and trust, launch arguments, telemetry, and providers.

Documentation

• Configuration reference
• Operational notes: permissions, credentials, isolation limits
• Development: build, test, and contribute
• Runbook: releases and bundled-plugin updates
• Example configurations
• Plugin guides: greenfield, orchestra, bigbrain, machine-security, dcouple

The bundled plugins are not all edited here. Maintainers publish plugins/dcouple/ from a separate source repository, and plugins/orchestra/ is generated from upstream by a script, so hand edits to either are overwritten. plugins/greenfield/ is written here, and so are plugins/machine-security/ and plugins/bigbrain/, except bigbrain's pinned copies of greenfield skills, which a script refreshes. See RUNBOOK.md.