Skip to content

Getting started

Prerequisites

  • tmux and git on your PATH.
  • At least one AI coding agent installed — e.g. Claude Code, Codex, Aider, Gemini, Amp, or opencode.
  • Linux or macOS. On Windows, run it inside WSL2.

No Go toolchain is required to install af — releases ship prebuilt binaries.

Install

curl -fsSL https://raw.githubusercontent.com/sachiniyer/agent-factory/master/install.sh | sh

This installs the af binary (Linux/macOS, amd64/arm64) to ~/.local/bin — override with AF_INSTALL_DIR, or pin a release with --version. Make sure ~/.local/bin is on your PATH.

Run af doctor --setup after install to verify tmux, git, your configured agent command, git identity, config/state/log storage, and daemon health.

You rarely need to update by hand: installed binaries auto-update on launch along the stable channel by default, at most once every 6 hours, and relaunch you into the new version on the spot. Set update_channel = "preview" in your global config to track preview builds instead, or auto_update = false to pin what you have (see the release process). To update on demand anyway, re-run the install script or run af upgrade.

Building from source instead? Clone the repo and run ./dev-install.sh (this needs Go).

Your first session

Sessions run in git worktrees, so most of the time you'll start inside a repository — that repo becomes the default project:

cd your-project    # a git repo
af doctor --setup  # optional but recommended on first run
af                 # launch the TUI, scoped to this project

You can also run af from anywhere: outside a git repository it opens on your project registry so you can pick a known project (or add one). Being in a repo just picks that repo for you.

Press Ctrl-p from the TUI (when you're not attached to a session pane) to switch projects without restarting. If you're attached to a pane, Ctrl-p goes to the running program — press Ctrl-] to detach first.

The TUI opens with an empty sidebar. From here:

  1. Press n to create a new session. Give it a name and, optionally, choose the agent with Tab. af creates a fresh git worktree on a new branch and starts your agent in it.
  2. The session appears in the sidebar with a live status. The Agent tab on the right shows a snapshot of the agent's terminal — you can watch its progress without attaching.
  3. Press ↵ (Enter) to interact with the selected agent right in the pane, or o to attach full-screen. From an in-pane interaction, Ctrl-] returns you to navigation mode; from a full-screen attach, the tmux detach key drops you back to the sidebar. Either way the agent keeps running. Use s to open a selected tab as a workspace pane; when a pane has focus, ← / → move focus between open panes.
  4. When you're done with a session, a archives it: tmux is torn down, the worktree is moved aside, and the session can be restored later. D permanently kills a session and removes its worktree/branch, including any uncommitted or unmerged work. If a session is marked Lost or Dead after a crash, reboot, or missing worktree, select it and press a or run af sessions restore <title> to recover it and resume its recorded agent conversation when possible.

Because each session is a real git branch, reviewing and merging an agent's work is just your normal git/PR flow.

Optional CLI equivalents

Everything the TUI does is also scriptable. Use these commands when you want shell automation, repeatable setup, or agent-to-agent workflows. The af sessions and af tasks command groups print JSON to stdout, so they compose with jq and shell:

af sessions create --name fix-auth-bug --prompt "Fix the login redirect loop"
af sessions list
af sessions preview fix-auth-bug          # snapshot its terminal
af sessions tab-create fix-auth-bug --command "npm run dev"   # a process tab in the worktree
af sessions attach fix-auth-bug           # attach interactively
af sessions archive fix-auth-bug          # finish with it, restorable later

Schedule an agent to run on its own:

af tasks add --name "Daily triage" --prompt "Triage open issues" --cron "0 9 * * *"

See the CLI reference for every command and flag, and Tasks & automation for schedules and watch scripts.

Keeping automations running across reboots

Scheduled and event-driven tasks are run by a background daemon, which starts on demand whenever there's work to host. To keep it (and your tasks) running across logouts and reboots, install its autostart unit once:

af daemon install

See The daemon for what it owns and why.

Next steps