Your First Agent

Spawn, peek, and clean up a fracta agent in about 5 minutes.

1. Initialize fracta in your project

   From inside any git repository:

   cd /path/to/your/git/project
   fracta init
   

   This creates a .fracta/ directory for state and worktrees. It does not modify your repo’s tracked files.

2. Spawn an agent

   fracta spawn --task hello --contract "Write a haiku about distributed systems."
   

   Fracta creates a worktree under .fracta/worktrees/hello, launches your default runtime CLI in that worktree, and tracks the agent in its state store.

   Useful flags:

   Flag	What it does
   --runtime	Override the default runtime (claude, codex, opencode). Default comes from your fracta.yaml.
   --mode	batch (default) — single-shot execution and return; stream — long-lived MCP session for follow-ups via fracta say.
   --tier	heavy, medium, or light — picks a model from your fracta.yaml model_tiers map.
   --model	Set the model directly (overrides config and tier).
   --base	Branch to base the worktree on (default from config, usually main).
   --contract	Inline contract text or a path to a contract file. Optional.
   --dry-run	Resolve the full spawn chain without creating an agent. Pair with --format yaml|json.

3. Watch progress

   fracta watch hello
   

   Streams the agent’s events (tool calls, output, status transitions) to your terminal in real time. Ctrl-C to detach without killing the agent.

4. See the result

   fracta peek hello
   

   Prints the agent’s recent semantic output. Run after the agent has completed (status completed in fracta list).

5. Clean up

   fracta kill hello
   

   fracta kill removes the agent’s worktree and state entry. The feature branch in the underlying git repo is also deleted. Make sure you’ve merged anything you want to keep.

Spawn multiple in parallel

fracta spawn --task task-a --contract "Refactor the auth module."
fracta spawn --task task-b --contract "Add a unit test for the cache."
fracta spawn --task task-c --contract "Update the README."

Then list them:

fracta list

Each agent runs independently, in its own worktree. They can message each other via fracta_send if you ask them to.

What’s next

Pick a Deployment Mode

Local-process vs docker-compose vs kubernetes.

Configure Your Runtime

Claude, Codex, and OpenCode setup.

CLI Reference

Every command and every flag.