GitHub - mieubrisse/agenc: The CEO command center for your fleet of Claudes

Why AgenC

If you're like most people, you use Claude like this:

Much better is John Rush's philosophy of Inputs, Not Outputs:

Each iteration makes all future outputs better.

But it doesn't scale.

The Claudes step on each other, you end up spawning heaps of side Claude windows, juggling the windows becomes a circus, and it's easy to forget what you even started working on.

AgenC tames this chaos. It provides:

• 📦 Claude session isolation in fully independent sandboxes (no Git worktrees, no merge queue - each agent is completely independent!)
• 🎨 Session management and command palette + hotkeys so launching new sessions, switching windows, stopping/resuming sessions, and rolling lessons back into your Claude config is a thought away
• 🔧 Palette customization so your top-used operations are easy

• 🔐 1Password secrets injection
• 🏗️ Claude orchestration so one Claude can spawn and coordinate other Claude teammates
• 🤖 An AI assistant that knows how to configure & drive AgenC so you never have to use CLI commands

And of course, AgenC is built with AgenC.

⚠️ ADDICTION WARNING ⚠️

AgenC feels great to use, like painting with your mind. But you should know it has a videogame-like addictive quality.

Because it's so easy launch work, you get a "just one more mission" feeling.

I noticed while building AgenC that it's hard to switch off and go to sleep. My brain would always be buzzing with ideas, and I'd wake up in the middle of the night wanting to launch new work.

Please remember to take breaks and leave sufficient wind-down time before sleep!

Quickstart

Prerequisites

• MacOS (for now)
• Claude Code installed and in your PATH

Install

brew tap mieubrisse/agenc
brew install agenc

This automatically installs required dependencies (gh, fzf, tmux).

If you're not logged in to gh, use:

1. 🔧 Initialize

The AgenC directory defaults to ~/.agenc. Override with AGENC_DIRPATH if needed.

Run the following and answer the prompts:

I recommend "yes" to creating a config repo; AgenC will sync it to GitHub automatically.

The AgenC interface is tmux. Run this so you get the AgenC keybindings:

If you haven't used tmux before, here's a starter ~/.tmux.conf:

set -g extended-keys on

# Ctrl-h goes to previous window
bind -n C-h previous-window

# Ctrl-l goes to next window
bind -n C-l next-window

# Ctrl-; toggles between panes inside a window
bind -n 'C-;' select-pane -t :.+

# Ctrl-shift-h moves a window to the left
bind -n C-S-h swap-window -t -1\; select-window -t -1

# Ctrl-shift-l moves a window to the right
bind -n C-S-l swap-window -t +1\; select-window -t +1

2. 🚀 Launch

AgenC's interface runs inside tmux. You can use it from any tmux session — agenc attach is just a convenience that creates or resumes a tmux session called agenc:

If you already have your own tmux workflow, you can skip agenc attach and use agenc commands directly from any tmux session. The command palette and keybindings work everywhere.

You'll be dropped into the repo selection screen. Select "Github Repo" and enter a repo you're working on.

AgenC will clone it, launch a new mission, and drop you into Claude to start your work.

Missions are the main primitive of AgenC: disposable self-contained workspaces with a fully independent copy of the Git repo (no merge queue needed - the agents figure it out, just like humans).

3. 🎨 Command Palette

Inevitably you'll want to do work on the side while Claude is grinding away.

Press ctrl-y to open the command palette and...

• 🐚 Open a side shell in your current mission's workspace ("Side Shell" or ctrl-p)

  💡 cmdk is amazing in the side shell

• 🚀 Launch a side mission ("New Mission" or ctrl-n, or "Side Claude" or "Quick Claude")
• 🔀 Switch between your running missions ("Switch Mission" or ctrl-m)
• 💬 Send me feedback about AgenC!

These commands are cheap; use them liberally. AgenC is designed to help you manage having 10+ threads going at once.

The command palette can be configured with custom hotkeys and custom commands.

The hard way to do this is through the CLI helpdocs the agenc config paletteCommand. For example, this is to quickly set up a new Github repo:

agenc config paletteCommand add newRepo \
    --title "🆕 New Repo" \
    --command "agenc mission new \
        --blank \
        --prompt 'I want to create a new GitHub repository. Please:
            1) Ask me what the repository name should be and whether I want it public or private
            2) Create it on GitHub using the gh CLI
            3) Initialize this blank mission directory as a git repo and set it up to track the newly created GitHub repository.'"

The easier way is through the Adjutant.

5. 🤖 Adjutant

AgenC has an AI assistant called Adjutant ("Adjutant" on the palette or ctrl-t for Side Adjutant) that knows how to configure AgenC, as well as launch and manage missions.

You can use the agenc config commands to configure stuff like palette commands... but now I just talk to the Adjutant for my AgenC configuration needs.

6. Mission Management

When you're done with a mission, you don't need to explicitly stop it — just detach and move on. Use "Detach Mission" (ctrl-i) on the command palette to unlink the current mission from your tmux window, or "Exit" to leave the AgenC tmux session entirely. Either way, your missions keep running in the background. After a period of inactivity, AgenC will automatically idle-kill them. You can always re-attach later with "Attach Mission" on the command palette, which will pick up right where you left off.

You can see all missions with agenc mission ls, and switch between missions with "Attach Mission" (ctrl-m) on the command palette.

If you want to explicitly stop a mission, you can use "Mission Stop" (ctrl-s) on the palette. Since each mission is an isolated workspace, no work is lost.

Full CLI docs: docs/cli/

6. 🔐 Secrets

If you create a .claude/secrets.env with 1Password CLI secret references in it, AgenC will resolve them on mission launch and inject them into Claude. This is useful for MCP server credentials.

For example:

.claude/secrets.env:

SUBSTACK_SESSION_TOKEN="op://Private/Substack Session Token/credential"
SUBSTACK_USER_ID="op://Private/Substack Session Token/username"

.mcp.json:

{
    "mcpServers": {
        "substack-api": {
            "command": "npx",
            "args": ["-y", "substack-mcp@latest"],
            "env": {
                "SUBSTACK_PUBLICATION_URL": "https://mieubrisse.substack.com/",
                "SUBSTACK_SESSION_TOKEN": "$SUBSTACK_SESSION_TOKEN",
                "SUBSTACK_USER_ID": "$SUBSTACK_USER_ID"
            }
        }
    }
}

7. Send feedback

I'd love to hear from you! To send me feedback you can...

• Use "Send Feedback" in the command palette
• Ask the Adjutant to send feedback
• Join the Discord using "Join Discord" on the command palette or use this link

Tips

• When things go wrong, upgrade! Pop off a new mission and fix the problem: patch the settings.json, upgrade the prompt, debug the issue. Missions are cheap; use them liberally. I'm often juggling 6-8 missions at any given time.

• Run Claude in sandbox mode. This cuts a lot of permission request fatigue. Run /sandbox once from vanilla Claude (not inside AgenC) to enable sandboxed command execution. This allows Claude to run commands without manual approval prompts on every action. The setting automatically carries into every new AgenC mission (or if you want to upgrade an existing Mission, do "Reconfig Mission" → "Reload Mission"). This is the recommended alternative to --dangerously-skip-permissions.

• Paint, don't code. Think in Bezos' Type 1 / Type 2 terms: Type 1 decisions are hard to reverse (security, data loss, architecture); Type 2 are easily undone (most implementation details). Act like a lightly-technical PM - set your guardrails in settings.json and CLAUDE.md, then let the agent make Type 2 decisions freely. Review outcomes, not every character. When something goes wrong, roll the lessons back into your config. Be okay with manageable messes; you can clean up WAY faster now.

• Commit & push after every turn. By default my agents commit after every turn, and also push to main for repos where I'm the only owner. Branches are for Type 1 decisions only. This occasionally causes some problems... but it's net SO much faster. And when your agents do dumb stuff, roll the lessons back into the Claude config so they get smarter.

• Rename missions when you stop them. Use /rename inside Claude to give a mission a descriptive name before exiting. This makes finding and resuming the right mission much easier later when you run "Resume Mission".

How It Works

AgenC runs several cooperating components that work together to give you a factory of Claudes:

Missions

A mission is AgenC's core primitive — a fully isolated workspace where one Claude works on one task.

When you create a mission, AgenC:

1. Clones a full copy of your Git repo into $AGENC_DIRPATH/missions/<uuid>/agent/. This is NOT a Git worktree — it's a complete independent clone. This means no merge queue, no conflicts with other missions, and no shared state. Each Claude has its own sandbox.

2. Builds a custom Claude config by copying your global ~/.claude config and injecting AgenC-specific niceties (e.g. skip the "Trust this project?" prompt).

3. Spawns a wrapper process that supervises the Claude session. The wrapper handles authentication, tracks mission health, and can restart Claude if needed.

Missions are disposable. You can stop them, resume them, or archive them. Work persists because each mission is a real Git repo — commit and push like normal.

Cross-Mission Orchestration

Missions aren't just isolated — they can spawn, monitor, and read each other. This makes AgenC a true factory: one Claude can delegate subtasks to other Claudes, wait for results, and incorporate the output.

Spawning a child mission:

From inside a running mission, a Claude can launch another mission targeting any repo in the library:

agenc mission new <repo> --prompt "Description of the work to do"

The --headless flag runs the child mission without a tmux window (useful for fully autonomous background work). The --no-focus flag keeps your current window focused after launch.

Monitoring status:

agenc mission inspect <mission-id>
# Status: IDLE = finished and waiting, BUSY = actively processing, STOPPED = not running

When the status shows IDLE, the child mission's agent has finished its work and is waiting for input.

Reading the conversation:

agenc mission print <mission-id>           # Last 20 lines
agenc mission print <mission-id> --all     # Full transcript
agenc mission print <mission-id> --tail 50 # Last 50 lines

This lets a parent mission read what the child Claude did — check its output, verify results, or extract information to continue its own work.

Typical pattern:

1. Parent mission spawns a child: agenc mission new myrepo --prompt "Run the test suite and report failures"
2. Parent periodically checks: agenc mission inspect <id> until status is IDLE
3. Parent reads the result: agenc mission print <id> --all
4. Parent incorporates the child's output into its own work

Wrapper

The wrapper is a supervisor process — one per active mission — that tends the Claude child process.

The wrapper:

• Passes authentication to Claude via the CLAUDE_CODE_OAUTH_TOKEN environment variable (more below)
• Tracks idle state by listening to hooks that fire when Claude starts and stops responding
• Writes heartbeats to the database every 30 seconds so the server knows which missions are alive
• Restarts Claude on command (via unix socket) — useful after upgrading Claude config or when something breaks
• Updates the repo library immediately when you push, so new missions get your changes without waiting

When Claude exits (naturally or via /exit), the wrapper cleans up and stops. The mission directory stays intact, so you can resume later.

Server

The server is a background process that keeps the factory running smoothly. It runs six concurrent loops:

1. Repo sync (every 60 seconds) — Fetches and fast-forwards repos in the shared library so new missions clone from fresh code without needing to run a slow git clone
2. Config auto-commit (every 10 minutes) — If your $AGENC_DIRPATH/config/ is a Git repo, the server auto-commits and pushes changes to Github so your config stays version-controlled

4. Config watcher (on file change) — Watches ~/.claude and mirrors changes to a shadow repo so missions can inherit your latest config
5. Keybindings writer (every 5 minutes) — Regenerates tmux keybindings to pick up any palette command changes

The server starts automatically when you run most agenc commands. If it crashes, just restart it with agenc server stop then agenc server start - running missions are unaffected.

Repo Library

AgenC maintains a repo library of Git repos at $AGENC_DIRPATH/repos/. When you create a mission, AgenC copies from this library instead of cloning from GitHub every time so that new don't require cloning from Github.

The server keeps the library fresh by fetching every 60 seconds. The wrapper contributes by watching for pushes: when you git push from a mission, the wrapper immediately updates the library copy so new missions get your changes. Existing missions will notice when they try to merge, same as a human.

Missions cannot read or modify the repo library directly (enforced via permissions). They only see their own workspace.

Authentication

Standard Claude Code authentication doesn't work well with multiple concurrent sessions because the tokens refresh and invalidate each other in a loop (GitHub issue).

AgenC solves this by using a long-lived OAuth token that you provide once during setup. The token is stored at $AGENC_DIRPATH/cache/oauth-token (mode 600, never committed to Git). When the wrapper spawns Claude, it reads this file and passes the token via the CLAUDE_CODE_OAUTH_TOKEN environment variable.

All missions share the same token, so there's no refresh thrashing. When the token expires, update it once with agenc config set claudeCodeOAuthToken <new-token>, and all new missions (plus running missions after restart) pick it up automatically.

The only downside I haven't yet figured out is these Claude tokens can't query usage, so the /usage command won't work in AgenC Claudes. You'll need to drop down to vanilla Claude to check your usage.

Configuration

AgenC stores its state in $AGENC_DIRPATH (defaults to ~/.agenc). The central configuration file is $AGENC_DIRPATH/config/config.yml.

Key features:

• Synced repos — keep repositories continuously up-to-date in a shared library

• Palette commands — customize the tmux command palette and keybindings
• Config auto-sync — optionally back the config directory with Git for automatic versioning

See docs/configuration.md for the full reference.

Troubleshooting

Run agenc doctor to check for common configuration issues.

"Command Line Tools are too outdated"

If you see this error during installation:

Error: Your Command Line Tools are too outdated.

This is a Homebrew requirement, not an AgenC issue. Homebrew requires up-to-date Xcode Command Line Tools to function, even when installing pre-built binaries.

To fix, update your Command Line Tools:

If that doesn't work, remove and reinstall:

sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

Then retry brew install agenc.

Upgrading AgenC

brew update
brew upgrade agenc
agenc server restart

Uninstall

agenc tmux uninject
agenc mission nuke -f
agenc server stop
brew uninstall agenc

This stops the agenc server and removes all mission assets. To remove the AgenC data directory itself:

If you customized AGENC_DIRPATH, remove that directory instead.

Local Development

Prerequisites

• Go (version specified in go.mod)
• golangci-lint, govulncheck, and deadcode (see below)

Install development tools

go install github.com/golangci/golangci-lint/cmd/golangci-lint@v2.11.4
go install golang.org/x/vuln/cmd/govulncheck@v1.1.4
go install golang.org/x/tools/cmd/deadcode@v0.43.0

These are the same versions pinned in CI. govulncheck and deadcode are official Go team tools from the golang.org/x/ extended repositories.

Build

This runs code generation, quality checks (formatting, vet, lint, vulnerability scan, dead code analysis, tests with race detection and coverage), and compiles the binary to _build/agenc.

Quality checks only

The pre-commit hook runs make check automatically on every commit, so you generally don't need to run this manually.

E2E tests

Builds the binary, creates an isolated test environment, runs integration tests against it, and tears down the environment.

CLI Reference

Run agenc --help for available commands, or see docs/cli/ for complete documentation.