Your first project

This guide uses the built-in SI Fabrik Board, so you don't need a tracker account. It takes about five minutes, plus however long the agent works.

Before you begin#

• Install the app and confirm Claude Code and Git pass the system check.
• For Docker isolation (recommended), start Docker, build the agent image and add a credential. You can also do this from the wizard.

Add the project#

1. Open Add Project

   Click Add Project at the bottom of the sidebar's Projects section, or press ⇧⌘N.

2. Choose a repository

   Click Choose or create a project folder… and pick a repository. For a brand-new project, use New Folder in the picker.

   If the folder isn't a git repository, SI Fabrik offers to initialize one: it runs git init -b main and makes an initial commit of README.md, WORKFLOW.md and .gitignore only, never other files in the folder. SI Fabrik clones your repository into a workspace for every task, so it needs git.

   If the folder already has a WORKFLOW.md, choose Use the existing workflow or Generate a new one (overwrites).

3. Pick where work comes from

   Choose SI Fabrik Board, the built-in Kanban stored in .symphony/board.json next to WORKFLOW.md. Leave Seed the board with a starter issue on to get a small documentation task to try. .symphony/ is added to .gitignore.

   For ClickUp or GitHub Issues, see Trackers.

4. Choose how agents run
   • Runner: Claude Code (default) or Codex app-server.
   • Model: the runner's default, or a specific model such as claude-opus-5-5. With a gateway, the gateway's default.
   • Route model traffic through LiteLLM: shown when a gateway is set up in Settings.
   • Run agents in Docker sandboxes: recommended. If you haven't added a credential yet, paste a claude setup-token token or an API key here. Without a sandbox, the project pauses with sandbox_policy until you turn on Edit Project → Allow agents to run directly on this Mac. See The sandbox floor.
   • When the agent hands off: Open a draft PR, Open a PR, or Keep the branch in my repo.

   Click Add Project. The wizard writes a commented WORKFLOW.md into the repository.

Run your first task#

1. Create a task in Todo

   Open the project's Board tab. The starter issue sits in Backlog, which isn't an active state, so nothing runs yet. Drag it to Todo, or press ⌘N for a New Issue: give it a title, a Markdown description (this becomes the agent's brief), a state and a priority.

2. Start the orchestrator

   Press Start in the project header. The orchestrator polls the board every 15 seconds (the template's polling.interval_ms), or right away when you press Refresh (⌘R). To skip the wait for one task, right-click it and choose Dispatch Now.

3. Watch the agent

   The card shows Agent running and its phase. Open Live Agents (⌘2) or the project's Agents tab to follow the transcript: assistant text, thinking, tool calls and results, with token and cost counters.

4. Review the hand-off

   When the agent finishes, it moves the task to Human Review and comments with a summary. SI Fabrik saves the branch symphony/<task-id> into your repository and, with a PR option chosen, pushes it and posts the pull request link on the task. Move the task to Done when you've merged it; SI Fabrik then cleans up the workspace.

What just happened#

1. The orchestrator found a task in an active state (Todo) and claimed it.
2. It created a workspace under workspace.root and cloned the project into it with git clone --no-local, on the branch symphony/<task-id>.
3. It rendered the prompt from WORKFLOW.md and started Claude Code in a Docker container with only that workspace mounted.
4. The agent worked through turns, using the board_* tools to comment and change state. Those tools ran on your Mac, with SI Fabrik's credentials.
5. When the task left the active states, SI Fabrik let the current turn finish, saved and pushed the branch, and opened the pull request.

See also#

• Core concepts
• The WORKFLOW.md guide
• Watch your agents