Prerequisites

Before installing Aigon, make sure you have:

Install prerequisites

macOS (Homebrew):

brew install node git tmux

Ubuntu / Debian:

sudo apt install nodejs npm git tmux

Fedora:

sudo dnf install nodejs npm git tmux

Arch:

sudo pacman -S nodejs npm git tmux

Note: On Ubuntu/Debian, the nodejs package may be outdated. For Node.js 18+, use the NodeSource  repository or nvm .

Installation

Clone the repository and link the CLI globally:

macOS:

git clone https://github.com/jayvee/aigon.git ~/src/aigon
cd ~/src/aigon
npm ci
npm link

Linux:

git clone https://github.com/jayvee/aigon.git ~/src/aigon
cd ~/src/aigon
npm ci
sudo npm link

Clone to ~/src/aigon or your preferred location for code repos. The path doesn’t matter as long as you keep it around — npm link creates a global symlink to this directory. On Linux, global npm commands (npm link, npm i -g) require sudo.

Verify the install:

aigon --version

Agent CLIs

Install at least one agent CLI to use Aigon:

Linux: prefix npm i -g commands with sudo (e.g., sudo npm i -g @google/gemini-cli).

You don’t need all of them — install whichever you have access to. Fleet mode works best with 2+ agents.

Optional tools

Verify your setup

Run the doctor command to check that everything is configured correctly:

aigon doctor

Doctor checks Node.js version, Git availability, tmux, and which agent CLIs are in your PATH.

Configure your terminal

Aigon launches agent sessions in terminal windows. Create your global config:

aigon config init --global

Then set your terminal. Pick the one you use:

iTerm2 (recommended — agents run in tabs within a single window):

aigon config set --global terminal tmux
aigon config set --global tmuxApp iterm2

Warp (agents run in side-by-side split panes):

aigon config set --global terminal warp

Terminal.app (macOS built-in — agents run in tmux sessions):

aigon config set --global terminal tmux

Default: terminal = warp. If you already use Warp, you can skip this step.

Initialize a project

Navigate to any Git repository and run:

cd /path/to/your/project
aigon init

This creates the docs/specs/ folder structure with Kanban lanes for features, research, and feedback.

Then install the agents you want to use:

aigon install-agent cc gg          # Claude Code + Gemini CLI

Install only the agents you have access to. You can add more later with aigon install-agent.

Tip: install-agent checks whether the agent CLI binary is in your PATH and warns you if it’s missing, so you’ll know immediately if you need to install something first.

Three ways to interact

All three surfaces drive the same underlying workflow. Mix them freely.

Your first feature

The fastest path from idea to implementation is feature-now. Describe what you want — the agent creates a spec, assigns an ID, sets up the workspace, and starts implementing:

/aigon:feature-now dark-mode
Add a dark mode toggle to the top-right of the site header.
Use CSS custom properties for theming. Default to system preference.
Store the user's choice in localStorage.

This is a normal agent conversation — you can go back and forth, refine requirements, ask questions, and iterate on the spec before the agent starts coding. The difference is that the conversation is anchored to a feature spec with acceptance criteria, so decisions are captured rather than lost in chat history.

Step by step (the full loop)

For more control, use the individual commands:

# 1. Create a feature — describe what you want
/aigon:feature-create dark-mode
Add a dark/light mode toggle with system preference detection...

# 2. Prioritise — assigns an ID, moves to backlog
/aigon:feature-prioritise dark-mode
# → Assigned ID: 07

# 3. Start — creates workspace, launches agent
/aigon:feature-start 07

# 4. Agent implements the spec...
#    → reads spec, explores codebase, writes code
#    → commits, writes implementation log
#    → signals "submitted" when done

# 5. Merge to main
/aigon:feature-close 07

Each step moves the feature through the pipeline: inbox → backlog → in-progress → done.

Try it end-to-end

Want to verify your installation works before using Aigon on a real project? Clone the seed repo — a small Next.js app with features already in the pipeline — and run a complete feature loop.

1. Set up the seed repo

git clone https://github.com/jayvee/brewboard-seed.git ~/src/brewboard
cd ~/src/brewboard
git remote remove origin        # prevent push errors — this is a local sandbox
npm install
aigon init
aigon install-agent gg          # or: aigon install-agent cc

Linux: use sudo npm link when installing aigon, and sudo npm i -g for agent CLIs.

2. Start a feature

The seed repo has features ready in the backlog. Pick one and start it:

aigon feature-start 02 gg       # Drive worktree mode with Gemini

This creates a worktree and launches Gemini in a tmux session. On macOS it opens a terminal window; on Linux it prints the attach command:

tmux attach -t brewboard-f2-gg-brewery-import

Each agent’s dev server runs on its own port (shown in the output, e.g. PORT=3001). You can preview the app at http://localhost:3001 while the agent works.

3. Start the server

The Aigon server provides the dashboard UI, agent supervisor, and WebSocket status updates. Install it as a persistent service so it starts automatically on login and restarts on crash:

aigon server start --persistent        # One-time: install as system service
aigon server add ~/src/brewboard       # Register the seed repo

Then open http://localhost:4100  in your browser. You’ll see the feature in the Pipeline view with the agent status updating in real-time.

What --persistent does: On macOS it installs a launchd agent; on Linux a systemd user service. The server survives terminal closes, Mac restarts, and process crashes — launchd/systemd will always bring it back. Logs are written to ~/.aigon/logs/server-*.log.

You can also run aigon server start (without --persistent) if you prefer a foreground process that stops when you close the terminal.

The server auto-restarts when you run aigon update. You only need to manually restart (aigon server restart) if you’re developing Aigon itself and editing lib/*.js files.

4. Close the feature

When the agent shows “Submitted”, close from the CLI or click “Accept & Close” in the dashboard:

aigon feature-close 02

What to expect at each step:

1. aigon init — creates docs/specs/ directories, rebuilds manifests for existing features
2. aigon install-agent — writes agent config files, warns if the agent CLI isn’t in your PATH
3. aigon feature-start — moves spec to in-progress, creates worktree, starts agent in tmux
4. aigon server start --persistent — installs the server as a system service; web UI at localhost:4100 showing pipeline, agent status, sessions. The Reports tab tracks token usage, cost, and throughput across agents — check it after your first feature to see telemetry in action
5. aigon feature-close — merges the feature branch to main, moves spec to done, cleans up

If anything goes wrong, run aigon doctor to diagnose the issue.

Updating Aigon

Updating Aigon is two steps:

1. Update the CLI — pull the latest code from GitHub:

cd ~/src/aigon && git pull && npm ci

2. Update your projects — happens automatically. The next time you start an agent session in any project, Aigon detects the version mismatch and re-runs aigon update to sync templates and agent configs. You can also run it manually:

cd /path/to/your/project
aigon update

If the dashboard is running, aigon update will restart it automatically to pick up the changes.

What’s next

• Drive Mode — hands-on implementation with one agent
• Fleet Mode — multiple agents competing in parallel
• Autonomous Mode — hands-off autonomous loops
• Execution Modes — Drive, Fleet, Autopilot, and Swarm