Topout

Open-source tool to manage multiple AI coding agents.

One click: branch, worktree, agent, terminal. All visible in one place.

Quick Start

npx topout

1. Add a repo — point Topout at an existing git repository
2. Create a workstream — enter a branch name, an agent launches automatically
3. Repeat — spin up as many as you need, all visible in the sidebar

That's it. Local-only, no account required.

What It Does

• Creates an isolated git worktree for each branch
• Launches an AI agent (Claude, Codex, etc.) in a tmux session per worktree
• Streams all agent terminals to a single web UI
• Manages the full lifecycle: create, monitor, interact, delete
• Runs locally on macOS and Linux

Prerequisites

• Node.js 22+
• tmux — brew install tmux (macOS) or apt install tmux (Linux)
• git
• An AI coding agent: Claude Code, Codex, or any CLI tool

CLI Options

| Flag | Default | Description | |------|---------|-------------| | --port <number> | 3000 | Port for the web UI | | --no-open | — | Don't auto-open the browser |

Environment variables:

• TOPOUT_DATA_DIR — data directory (default: ~/.topout)

Configuration

Topout uses a three-tier configuration hierarchy. Each tier can define session configs (what tools to launch) and lifecycle hooks (scripts to run during setup).

System (built-in)  →  User (~/.topout/config/)  →  Repo (<repo>/.topout/)

Higher tiers override lower tiers. The repo tier has the final say.

Directory Structure

User-level (~/.topout/config/):

~/.topout/config/
├── sessions/
│   └── <id>.yml          # session configs
└── hooks/
    ├── repo_add/
    │   └── <id>.yml      # run when a repo is added
    └── workstream_setup/
        └── <id>.yml      # run when a workstream is created

Repo-level (<repo>/.topout/):

<repo>/.topout/
├── sessions/
│   └── <id>.yml
└── hooks/
    ├── repo_add/
    │   └── <id>.yml
    └── workstream_setup/
        └── <id>.yml

Sessions

Session configs define tools that can be launched inside a workstream. Topout ships with built-in presets for Claude Code and Codex. To add your own, create YAML files in ~/.topout/config/sessions/ (user-level) or <repo>/.topout/sessions/ (repo-level).

# ~/.topout/config/sessions/aider.yml
name: Aider
icon: terminal-square
description: AI pair programming
singleton: true
auto_start: true
hooks:
  startup: aider
  shutdown:
    signal: SIGTERM
    grace_period_ms: 5000
env:
  AIDER_MODEL: claude-sonnet-4-20250514

Fields:

| Field | Required | Default | Description | |-------|----------|---------|-------------| | name | yes | — | Display name in the UI | | icon | yes | — | Icon identifier (e.g. terminal-square, tool:claude) | | description | no | — | Short description shown in the session picker | | singleton | no | false | Only allow one instance per workstream | | auto_start | no | — | Automatically launch when a workstream is created | | hooks.startup | no | — | Shell command to run in the session's terminal | | hooks.shutdown.signal | no | — | Signal to send on shutdown (e.g. SIGTERM) | | hooks.shutdown.grace_period_ms | no | — | Time to wait after signal before force-killing | | hooks.shutdown.command | no | — | Command to run on shutdown instead of a signal | | env | no | — | Environment variables passed to the session | | enabled | no | — | Set to false to disable an inherited config |

Session configs appear in the "+" menu when adding sessions to a workstream.

Merge behavior: Sessions merge by full replacement — if a repo defines a session with the same ID as a user or system config, the repo version completely replaces it. Set enabled: false to disable an inherited session without replacing it.

Auto-start: Sessions with auto_start: true launch automatically after workstream creation. When a repo is first added, auto-start sessions wait for setup hooks to finish before launching — this ensures hooks like dependency installation complete before agents start.

Lifecycle Hooks

Hooks are shell commands that run at specific points in the setup lifecycle. They execute in a visible "Setup" terminal so you can see their output.

Trigger events:

| Event | When it runs | |-------|-------------| | repo_add | Once when a repository is first added to Topout | | workstream_setup | Each time a workstream is created |

When a repo is added, both events fire in order: repo_add hooks first, then workstream_setup hooks.

Hook YAML schema:

# ~/.topout/config/hooks/workstream_setup/install-deps.yml
command: npm install
after: some-other-hook
enabled: true

| Field | Required | Default | Description | |-------|----------|---------|-------------| | command | yes | — | Shell command to execute | | after | no | — | ID of another hook to run after (controls ordering) | | enabled | no | true | Set to false to disable an inherited hook |

The hook ID is derived from the filename (e.g. install-deps.yml → ID install-deps). Use after to control execution order when multiple hooks exist for the same event.

Merge behavior: Hooks merge at the field level — if a repo defines a hook with the same ID as a user or system hook, only the fields specified in the repo config override; unspecified fields inherit from the lower tier. Set enabled: false to disable an inherited hook.

Environment variables available to hook scripts:

| Variable | Description | |----------|-------------| | TOPOUT_WORKSTREAM_TYPE | repo or worktree | | TOPOUT_WORKSTREAM_PATH | Absolute path to the workstream directory | | TOPOUT_WORKSTREAM_BRANCH | Git branch name | | TOPOUT_REPO_PATH | Absolute path to the repository root | | TOPOUT_API_BASE | Topout server URL (e.g. http://localhost:3000) |

System Configs

Topout ships with a built-in system hook:

• setup-claude-hooks (repo_add) — configures Claude Code to report session status back to Topout via HTTP hooks

System configs can be disabled at the user or repo level by creating a config with the same ID and enabled: false:

# ~/.topout/config/hooks/repo_add/setup-claude-hooks.yml
# Disables the built-in Claude Code hooks setup
enabled: false

Re-run Setup

If you need to re-run setup hooks for a repo (e.g. after changing hook configs), right-click the repo in the sidebar and select Re-run setup.

Security

Do not put secrets in .topout/. This directory is intended to be committed to version control and shared with your team.

Repo-level configs can execute arbitrary shell commands, similar to Makefile or .vscode/tasks.json. Only add repos you trust. Use environment variables or external secret managers for sensitive values.

Telemetry

Topout collects anonymous usage telemetry (operation types, durations, error counts) to help improve the product. No file paths, repo URLs, branch names, or user content is ever collected.

To disable: OTEL_SDK_DISABLED=true npx topout or set {"enabled": false} in ~/.topout/config/telemetry.json.

See the full telemetry docs for configuration options.

License

Topout is licensed under AGPL-3.0. You can freely use, modify, and self-host it. If you modify Topout and offer it as a service, you must share your changes under the same license.