Quickstart

This tutorial walks you through the complete Fabriq experience — from opening the app for the first time to reviewing and shipping code written by an AI agent.

What you'll need

• Fabriq installed on your machine
• A local project on your computer with a git repository
• An AI coding agent installed: OpenCode or Claude Code

Step 1: Launch Fabriq and connect a workspace

Fabriq works with your existing projects. A workspace is simply a folder on your computer that contains your code.

1. Open Fabriq Desktop

2. You'll see the welcome screen with a Connect Workspace button

   The welcome screen is the main entry point. It shows: a button to connect a workspace, a list of recent workspaces (empty on first launch), and links to settings.

3. Click Connect Workspace

4. Browse to a project folder on your computer (any folder with a git repository works)

5. Select it — Fabriq scans the folder and shows you its structure

   After selecting a folder, the Workspace Browser opens. The left panel shows your project's file tree. The right panel shows a list of feature worktrees (empty for now).

6. A dialog asks you to choose your AI agent — select OpenCode or Claude Code

   If you haven't installed an agent yet, you can skip this step and set it up later in Settings.

Your workspace is now connected. You should see your project files in the left panel.

Step 2: Create your first feature

Now you'll create a feature — a task for the AI agent to work on. Each feature gets its own isolated workspace where the agent can write code without touching your main project.

1. In the Workspace Browser, click the New Feature button (top of the right panel)

   A dialog opens asking for a feature name and description.

2. Enter a name: add-dark-mode

3. Write a description of what you want:

   Add a dark mode toggle to the settings page.
   - Use CSS custom properties (variables) for colors
   - Default to the system preference using prefers-color-scheme
   - Let users toggle between light/dark with a switch
   - Persist the preference in localStorage

4. Click Create

   Fabriq creates an isolated git worktree — a separate copy of your codebase where the agent can work freely. You'll see the Feature Workbench open, showing the pipeline stages.

Step 3: Watch the agent at work

The Feature Workbench shows you what's happening in real time.

What you see in the workbench:

┌─────────────────────────────────────────────┐
│  Feature: add-dark-mode                      │
│                                              │
│  Pipeline:  Design → Implement → Review → Ship │
│                ●●○○○○○○○○○ (25%)             │
│                                              │
│  ┌─ Activity Log ─────────────────────────┐  │
│  │ ✓ Created worktree branch              │  │
│  │ ✓ Read project files for context       │  │
│  │   Found: src/styles/variables.css      │  │
│  │   Found: src/pages/Settings.jsx        │  │
│  │ ⏳ Writing src/styles/theme.css        │  │
│  │ ⏳ Awaiting confirmation:              │  │
│  │   "Write 45 lines to theme.css"        │  │
│  │   [Approve] [Reject] [Skip]            │  │
│  └────────────────────────────────────────┘  │
│                                              │
│  ┌─ File Changes ─────────────────────────┐  │
│  │  + src/styles/theme.css        (new)   │  │
│  │  ± src/pages/Settings.jsx     (3 lines)│  │
│  └────────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

The agent works through a pipeline of stages:

Stage	What happens
Design	The agent reads your project to understand the codebase
Implement	The agent writes code — you see files being created and modified
Review	The agent finishes and presents the changes for your approval
Ship	Approved changes are merged into your main branch

Confirmation prompts

When the agent needs to take a destructive action (writing a file, running a command), Fabriq pauses and asks for your confirmation:

• Approve — let the action proceed
• Reject — block it and tell the agent to try a different approach
• Skip — defer the decision, come back to it later

For example, when the agent wants to write src/styles/theme.css, a prompt appears showing the file path, the content to be written, and the Approve/Reject/Skip buttons. You can read through the code before approving.

What you can do while the agent works

• Watch in real time — the activity log streams every action as it happens
• Leave it running — the agent works independently; come back later
• Interrupt — if the agent goes in the wrong direction, you can provide new instructions

Step 4: Review and approve the changes

When the agent finishes the Implement stage, the pipeline moves to Review.

1. Click on the Review tab in the workbench

   The review screen shows a side-by-side diff of every changed file, along with validation results.

2. Check the validation badges at the top:

   • ✅ Lint — code style is consistent
   • ✅ Type check — no TypeScript errors
   • ✅ Tests — all tests pass (if your project has tests)

3. Look through each changed file in the diff view

   The diff view shows your original code on the left and the agent's changes on the right. Added lines are green, removed lines are red.

4. If something needs fixing:

   • Click on the file
   • Leave a comment (e.g., "Please use CSS variables instead of hardcoded colors")
   • Click Request Changes
   • The agent reads your feedback and revises the code

5. When everything looks good, click Approve

Step 5: Ship the feature

After you approve:

1. Fabriq merges the agent's changes into your main branch
2. The feature worktree is archived (you can still access it later)
3. A feature report is saved — it includes what was changed, what the agent did, and what you approved

Your changes are now on your main branch, just like a regular merge. Open your project in your editor — the dark mode toggle is there.

What you've learned

In this tutorial, you:

• ✅ Connected a workspace to Fabriq
• ✅ Created a feature with a description
• ✅ Watched an AI agent write code in an isolated worktree
• ✅ Reviewed and approved changes
• ✅ Shipped AI-assisted code to your main branch

Next steps

• Creating Features in Detail — tips for writing better feature descriptions
• Reviewing Changes — how to do a thorough code review
• Undoing Changes — what to do if something goes wrong
• Understanding Workspaces — how Fabriq organizes your project