Skip to main content
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:
FlagWhat it does
--runtimeOverride the default runtime (claude, codex, opencode). Default comes from your fracta.yaml.
--modebatch (default) — single-shot execution and return; stream — long-lived MCP session for follow-ups via fracta say.
--tierheavy, medium, or light — picks a model from your fracta.yaml model_tiers map.
--modelSet the model directly (overrides config and tier).
--baseBranch to base the worktree on (default from config, usually main).
--contractInline contract text or a path to a contract file. Optional.
--dry-runResolve 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.