codeherd

A CLI for managing parallel agentic coding sessions. It organizes projects and git worktrees, configures per-agent environments with deterministic port allocation, and orchestrates tmux sessions where AI coding agents run independently.

It is like a shepherd, but for coding agents.

Why

Running multiple AI coding agents in parallel requires isolated workspaces, separate environments, and session management. codeherd handles the infrastructure -- git worktrees for isolation, tmux sessions for persistence, deterministic ports to avoid conflicts -- so each agent gets a clean, independent workspace without manual setup.

How It Works

codeherd manages a lifecycle that takes a project from configuration to a running agent session:

Clone -> Worktree -> File Copy -> Template Processing -> Session Start

Each step has pre/post hooks for custom automation (install dependencies, start services, notify external systems). See docs/hooks.md for the full hook lifecycle reference.

Configuration

All configuration lives in ~/.config/codeherd/config.toml. Here is a full example:

[defaults]
projects_dir = "~/projects"    # base directory for clones and worktrees
agent = "claude"               # default agent for new sessions

# ── Agents ──────────────────────────────────────────────────────────────────

[agents.claude]
cmd = "claude"
args = ["--dangerously-skip-permissions"]

[agents.claude.env]
CLAUDE_CONFIG_DIR = "/home/user/.config/claude"

[agents.aider]
cmd = "aider"
args = ["--model", "opus"]

[agents.codex]
cmd = "codex"
args = ["--approval-mode", "full-auto"]

# ── Projects ────────────────────────────────────────────────────────────────

[projects.myapp]
repo = "git@github.com:user/myapp.git"
default_branch = "main"

# Files copied into every new worktree (see File Copy section)
files = [
  "CLAUDE.md",                                       # same path in worktree
  ".cursorrules",                                     # same path in worktree
  "~/.config/codeherd/prompts/safety.md:RULES.md",   # absolute source, custom destination
]

# Hooks run at each lifecycle step (see Hooks section)
[projects.myapp.hooks]
post-clone = "make deps"
post-worktree = "npm install"
pre-session = "docker compose up -d"
post-session = "curl -s https://hooks.example.com/started"

[projects.api]
repo = "git@github.com:user/api.git"
default_branch = "develop"
files = [".envrc"]

[projects.api.hooks]
post-worktree = "bundle install"

Projects

Each project points to a git repository and a default branch. Clone paths mirror the repo URL under projects_dir:

~/projects/
  github.com/user/
    myapp/                    # main clone
    myapp__worktrees/
      feature/                # worktree for "feature" branch
      fix-123/                # worktree for "fix-123" branch
    api/                      # another project

Agents

Agents are CLI tools configured once and selected at session start. Any command-line tool works -- Claude Code, Aider, Codex, or a custom script. Each agent defines a command, optional arguments, and optional environment variables.

Profiles

Profiles let one machine carry several independent codeherd configs — e.g. a personal and a work set of projects and agents. Enable them in the main config and keep each profile as its own TOML file under profiles_dir:

[defaults]
profiles_enabled = true
profiles_dir = "~/.config/codeherd/profiles"   # default: <config dir>/profiles
main_profile = "personal"                       # used when nothing else selects one

Each <profiles_dir>/<name>.toml is a full config (its own projects, agents, projects_dir). When profiles_enabled = true, projects/agents/projects_dir in the main config are ignored (with a warning).

The active profile is resolved by precedence, lowest to highest:

defaults.main_profile in the main config
the CODEHERD_PROFILE environment variable
the --profile / -p flag

codeherd stamps CODEHERD_PROFILE into every profile-mode session, so a nested ch call inside a session (for example ch run <agent>) defaults to that session's profile without needing --profile.

Sessions

Sessions are tmux sessions anchored to a project and branch. They run independently and persist across disconnects:

tmux sessions:
  codeherd         # TUI dashboard
  myapp-feature    # Claude Code working on feature
  myapp-fix-123    # Aider fixing a bug
  api-experiment   # another agent exploring an idea

Session environment

codeherd stamps a fixed set of CODEHERD_* environment variables on every session it starts (both agent and shell). Use them in the agent's cmd/args or in scripts the agent invokes:

Variable	Value	Notes
`CODEHERD_SESSION`	Canonical session name, e.g. `myapp-feature`	Always set
`CODEHERD_PROJECT`	Project name from config	Always set
`CODEHERD_BRANCH`	Branch name	Always set
`CODEHERD_CLONE_DIR`	Absolute path to the main git clone	Set whenever the project has a valid `repo` URL. Needed by anything that runs `git` inside a worktree — git worktrees keep `.git` as a file that points back to the main clone
`CODEHERD_WORKTREE_PATH`	Absolute path to the worktree root	Always set
`CODEHERD_PROFILE`	Active profile name	Only set when a profile is active. Nested `ch` calls inherit it as the default profile (see Profiles)

These values win over any conflicting keys in [agents.<name>].env — the agent-level env is applied first, then codeherd's values are stamped on top.

Example: sandbox an agent with ai-jail while keeping git operations working:

[agents.claude-sandboxed]
cmd = "ai-jail"
args = ["--rw-map", "$CODEHERD_WORKTREE_PATH", "--rw-map", "$CODEHERD_CLONE_DIR", "--", "claude"]

Lifecycle

When you create a worktree and start a session, codeherd runs through a five-step lifecycle. Each step has optional pre/post hooks.

 Clone ──> Worktree ──> File Copy ──> Template Processing ──> Session Start
  │  │      │  │         │  │          │  │                    │  │
 pre post  pre post     pre post      pre post                pre post

File Copy

The files list in project config copies files into new worktrees. This is useful for shared configuration (editor rules, prompt files, env configs) that should exist in every worktree but isn't tracked in git.

Entry format	Source	Destination
`"CLAUDE.md"`	Clone dir / `CLAUDE.md`	Worktree / `CLAUDE.md`
`"src/config.json"`	Clone dir / `src/config.json`	Worktree / `src/config.json`
`"~/.config/prompts/safety.md:RULES.md"`	`~/.config/prompts/safety.md`	Worktree / `RULES.md`
`"/absolute/path/file.txt:subdir/file.txt"`	`/absolute/path/file.txt`	Worktree / `subdir/file.txt`

Relative paths resolve from the clone directory. Absolute paths and ~/ paths copy from the filesystem. Intermediate directories are created automatically.

Template Processing

After files are copied, codeherd scans the worktree for .herd files and renders them using Go's text/template engine. The rendered output is written as a sibling file without the .herd suffix:

.env.herd renders to .env
docker-compose.yml.herd renders to docker-compose.yml
nginx.conf.herd renders to nginx.conf

This is how you generate per-worktree configuration with unique ports and branch-specific values.

Template Variables

Templates receive a context object with these fields:

Variable	Type	Description	Example value
`.Project`	string	Project name from config	`myapp`
`.Branch`	string	Branch name	`feature`
`.WorktreePath`	string	Absolute path to the worktree	`/home/user/projects/github.com/user/myapp__worktrees/feature`
`.SessionName`	string	Derived session name	`myapp-feature`

Template Functions

Function	Description	Example
`port "name"`	Deterministic port (10000-59999) derived from project + branch + name. Same inputs always produce the same port, different branches get different ports.	`{{ port "http" }}`
`env "VAR" "default"`	Read an environment variable, with an optional fallback value.	`{{ env "API_KEY" "dev-key" }}`

Example: `.env.herd`

# .env.herd — place this in your repo or copy it via the files list
APP_PORT={{ port "http" }}
GRPC_PORT={{ port "grpc" }}
DEBUG_PORT={{ port "debug" }}
DATABASE_URL=postgres://localhost:5432/{{ .Project }}_{{ .Branch }}
API_KEY={{ env "API_KEY" "dev-key-for-local" }}
SESSION={{ .SessionName }}

Running ch create worktree myapp feature renders this to .env:

# .env (generated)
APP_PORT=34521
GRPC_PORT=18973
DEBUG_PORT=42810
DATABASE_URL=postgres://localhost:5432/myapp_feature
API_KEY=dev-key-for-local
SESSION=myapp-feature

Every worktree gets unique ports. The feature branch and fix-123 branch will never collide.

Example: `docker-compose.yml.herd`

# docker-compose.yml.herd
services:
  postgres:
    image: postgres:16
    ports:
      - "{{ port "postgres" }}:5432"
    environment:
      POSTGRES_DB: {{ .Project }}_{{ .Branch }}
      POSTGRES_PASSWORD: {{ env "PG_PASSWORD" "devpass" }}

  redis:
    image: redis:7
    ports:
      - "{{ port "redis" }}:6379"

Hooks

Hooks are shell commands that run at each lifecycle step. Configure them per-project:

[projects.myapp.hooks]
pre-clone = "echo preparing to clone"
post-clone = "make deps"
pre-worktree = "echo creating worktree"
post-worktree = "npm install"
pre-copy = "echo copying files"
post-copy = "chmod 600 .env"
pre-template = "vault read secret/myapp > .secrets"
post-template = "echo templates rendered"
pre-session = "docker compose up -d"
post-session = "curl -s https://hooks.example.com/started"

Hooks receive context as environment variables (CODEHERD_PROJECT, CODEHERD_BRANCH, CODEHERD_WORKTREE_PATH, etc.). A non-zero exit code stops the workflow. Omit a hook to skip it.

See docs/hooks.md for the full reference including environment variables per step, working directory rules, and error handling.

Install

Via mise

mise use github:xico42/codeherd@latest

Once codeherd lands in the mise official registry, this becomes mise use codeherd@latest.

Manual

Download the appropriate archive from the latest release, extract, and place ch on your PATH. Each release ships archives for linux and darwin on amd64 and arm64, with sigstore signatures and a checksums.txt.

From source

Requires Go 1.22+, git, and tmux.

make install    # builds and installs to ~/.local/bin/ch

Shell Completion

ch ships dynamic completion for agents, projects, profiles, and worktree branches. Cobra generates per-shell scripts via ch completion <shell>.

# zsh — ensure the dir is on your $fpath, then reload
ch completion zsh > "${fpath[1]}/_ch"

# bash
ch completion bash | sudo tee /etc/bash_completion.d/ch > /dev/null

# fish
ch completion fish > ~/.config/fish/completions/ch.fish

Completion respects the active profile: inside a profile-mode session ($CODEHERD_PROFILE set) or with -p <profile>, branch suggestions come from that profile's worktrees.

Quick Start

# Configure a project (edit ~/.config/codeherd/config.toml)
# See the Configuration section above for the full config format

# Clone the project
ch clone project myapp

# Create a worktree and start a session
ch create session myapp feature --agent claude --attach

Or use the interactive TUI:

ch

Commands

Command	Description
`ch`	Launch the TUI dashboard
`ch list project`	List configured projects
`ch show project <name>`	Show project details
`ch clone project <name>`	Clone a project
`ch list worktree`	List all worktrees
`ch create worktree <project> <branch>`	Create a worktree
`ch delete worktree <project> <branch>`	Delete a worktree
`ch list session`	List active sessions
`ch create session <project> <branch>`	Start an agent session (use `--shell` for a plain shell)
`ch attach session <project> <branch>`	Attach to a session
`ch show session <project> <branch>`	Show session details
`ch delete session <project> <branch>`	Stop a session
`ch version`	Print the installed version

Development

make build          # build ./ch binary
make test           # run unit tests
make lint           # run linter
make check          # coverage (80%+) + integration tests + lint + build

Documentation

Project overview -- architecture, design philosophy, and roadmap
Hooks lifecycle -- hook configuration, file copy, template processing

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.agents/skills		.agents/skills
.claude-plugin		.claude-plugin
.claude		.claude
.github/workflows		.github/workflows
cmd		cmd
docs		docs
internal		internal
plugins/claude		plugins/claude
.gitignore		.gitignore
.golangci.yml		.golangci.yml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
VERSION		VERSION
go.mod		go.mod
go.sum		go.sum
main.go		main.go
skills-lock.json		skills-lock.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

codeherd

Why

How It Works

Configuration

Projects

Agents

Profiles

Sessions

Session environment

Lifecycle

File Copy

Template Processing

Template Variables

Template Functions

Example: `.env.herd`

Example: `docker-compose.yml.herd`

Hooks

Install

Via mise

Manual

From source

Shell Completion

Quick Start

Commands

Development

Documentation

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

codeherd

Why

How It Works

Configuration

Projects

Agents

Profiles

Sessions

Session environment

Lifecycle

File Copy

Template Processing

Template Variables

Template Functions

Example: .env.herd

Example: docker-compose.yml.herd

Hooks

Install

Via mise

Manual

From source

Shell Completion

Quick Start

Commands

Development

Documentation

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Example: `.env.herd`

Example: `docker-compose.yml.herd`

Packages