Project Structure - Automagik Suite Documentation

Overview

Forge creates a specific directory structure to organize tasks, worktrees, configuration, and data. Understanding this structure helps you work effectively with Forge.

Directory Structure

your-project/
├── .forge/                    # Forge configuration and data
│   ├── config.json           # LLM and Forge settings
│   ├── forge.db              # SQLite database
│   ├── worktrees/            # Git worktrees for tasks
│   │   ├── task-1-auth/      # Isolated workspace for task 1
│   │   ├── task-2-api/       # Isolated workspace for task 2
│   │   └── ...
│   └── logs/                 # Execution logs
│       ├── task-1.log
│       └── ...
├── .git/                      # Your Git repository
├── .gitignore                # Don't commit .forge/!
├── src/                      # Your source code
├── package.json
└── ...

Always add .forge/ to .gitignore! This directory contains:

API keys and secrets
Local database
Temporary worktrees
Execution logs

echo ".forge/" >> .gitignore

The `.forge/` Directory

Configuration Files

file

Main configuration file containing LLM settings, OAuth tokens, and preferences

{
  "llms": {
    "claude": { "apiKey": "...", "model": "..." },
    "gemini": { "apiKey": "...", "model": "..." }
  },
  "worktrees": {
    "enabled": true,
    "basePath": "./.forge/worktrees"
  },
  "preferences": {
    "defaultLLM": "claude",
    "autoCleanup": true
  }
}

file

SQLite database storing:

Projects and tasks
Task attempts and results
Execution history
User preferences

This file is created automatically on first run. Backup regularly if you want to preserve history!

Worktrees Directory

Git Worktrees Explained

What Are Worktrees?

Git worktrees allow multiple working directories from the same repository. Forge uses this for task isolation.

Main Branch:
your-project/           ← Your main working directory
└── src/

Task Worktrees:
.forge/worktrees/
├── task-1/             ← Isolated copy for task 1
│   └── src/
└── task-2/             ← Isolated copy for task 2
    └── src/

Why Worktrees?

Complete Isolation

Each task works in its own environment - no conflicts!

Parallel Execution

Run multiple AI agents simultaneously on different tasks

Safe Experimentation

Try risky changes without affecting your main codebase

Easy Comparison

Compare different approaches side-by-side

How It Works

Create Task

You create a task in Forge: “Add user authentication”

Forge Creates Worktree

git worktree add .forge/worktrees/task-1-auth

Creates a complete copy of your repo at current commit

AI Works in Isolation

Claude modifies files in .forge/worktrees/task-1-auth/Your main directory is untouched

Review Changes

Compare worktree with main branch:

git diff main task-1-auth

Merge When Ready

If you approve:

git merge task-1-auth
git worktree remove .forge/worktrees/task-1-auth

Database Schema

The .forge/forge.db SQLite database contains:

Projects Table

CREATE TABLE projects (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  repository_url TEXT,
  default_llm TEXT,
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);

Tasks Table

CREATE TABLE tasks (
  id TEXT PRIMARY KEY,
  project_id TEXT REFERENCES projects(id),
  title TEXT NOT NULL,
  description TEXT,
  status TEXT, -- 'pending', 'in_progress', 'completed', 'failed'
  priority TEXT, -- 'low', 'medium', 'high'
  labels TEXT, -- JSON array
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);

Attempts Table

CREATE TABLE attempts (
  id TEXT PRIMARY KEY,
  task_id TEXT REFERENCES tasks(id),
  llm TEXT NOT NULL, -- 'claude', 'gemini', etc.
  worktree_path TEXT,
  status TEXT, -- 'running', 'completed', 'failed'
  output_log TEXT,
  created_at TIMESTAMP,
  completed_at TIMESTAMP
);

Backup & Restore

Backing Up Forge Data

# Backup configuration and database
tar -czf forge-backup-$(date +%Y%m%d).tar.gz .forge/

# Or just the essentials
cp .forge/config.json config-backup.json
cp .forge/forge.db forge-backup.db

Restoring From Backup

# Restore full backup
tar -xzf forge-backup-20240115.tar.gz

# Or restore specific files
cp config-backup.json .forge/config.json
cp forge-backup.db .forge/forge.db

Restoring worktrees requires active Git branches. Usually better to just restore config and database.

Cleanup & Maintenance

Clean Old Worktrees

# List all worktrees
git worktree list

# Remove specific worktree
git worktree remove .forge/worktrees/task-1-old

# Remove all stale worktrees (Forge does this automatically)
git worktree prune

Clean Old Logs

# Remove logs older than 30 days
find .forge/logs -name "*.log" -mtime +30 -delete

Compact Database

# Reduce database size
sqlite3 .forge/forge.db "VACUUM;"

Complete Clean

# Nuclear option: Remove everything Forge-related
rm -rf .forge/

# Restart Forge to recreate
forge start

This deletes all task history, configurations, and worktrees. Backup first!

Multi-User Scenarios

Personal Projects

your-project/
└── .forge/              # Your personal Forge data
    └── config.json      # Your API keys

Standard setup - one developer, one Forge instance

Team Projects

Each team member has their own .forge/ directory:

Alice's machine:
your-project/
└── .forge/              # Alice's Forge data

Bob's machine:
your-project/
└── .forge/              # Bob's Forge data (different)

Add .forge/ to .gitignore so team members don’t conflict

Shared Forge Instance (Advanced)

For teams sharing one Forge deployment:

Server:
/opt/forge/
├── projects/
│   ├── project-a/
│   │   └── .forge/
│   └── project-b/
│       └── .forge/
└── shared-config/

Best Practices

Version Control .gitignore

.gitignore

# Forge
.forge/
.forge.*

# But keep examples
!.forge.example.json

Document Structure

Add a README explaining Forge setup:

## Forge Setup

Install: `npm i -g automagik-forge`
Configure: `cp .forge.example.json .forge/config.json`
Add API keys to `.forge/config.json`

Regular Backups

# Add to cron
0 0 * * * cd ~/my-project && \
  cp .forge/forge.db ~/.backups/forge-$(date +%F).db

Clean Worktrees

Let Forge auto-cleanup, or manually:

forge worktree cleanup

Troubleshooting

Worktree conflicts

Error: “fatal: ‘task-1’ is already checked out at ‘.forge/worktrees/task-1’”Solution:

# Remove the worktree
git worktree remove --force .forge/worktrees/task-1

# Or let Forge handle it
forge worktree cleanup

Database locked

Error: “database is locked”Solution:

Close all Forge instances
Check for zombie processes: ps aux | grep forge
Kill if needed: pkill -f forge
Restart Forge

Missing config.json

Error: “Configuration file not found”Solution:

# Re-initialize
forge init

# Or restore from backup
cp config-backup.json .forge/config.json

Disk space issues

Error: “No space left on device”Solution: Worktrees accumulate. Clean them:

# Check size
du -sh .forge/worktrees

# Remove old worktrees
forge worktree cleanup

# Or manually
git worktree prune
rm -rf .forge/worktrees/*

Next Steps

Creating Tasks

Learn how to create and manage tasks

Git Worktrees

Deep dive into worktree concepts

Environment Variables

Advanced configuration options

CLI Reference

Command-line interface guide

​Overview

​Directory Structure

​The .forge/ Directory

​Configuration Files

​Worktrees Directory

​Git Worktrees Explained

​What Are Worktrees?

​Why Worktrees?

Complete Isolation

Parallel Execution

Safe Experimentation

Easy Comparison

​How It Works

​Database Schema

​Projects Table

​Tasks Table

​Attempts Table

​Backup & Restore

​Backing Up Forge Data

​Restoring From Backup

​Cleanup & Maintenance

​Clean Old Worktrees

​Clean Old Logs

​Compact Database

​Complete Clean

​Multi-User Scenarios

​Personal Projects

​Team Projects

​Shared Forge Instance (Advanced)

​Best Practices

Version Control .gitignore

Document Structure

Regular Backups

Clean Worktrees

​Troubleshooting

​Next Steps

Creating Tasks

Git Worktrees

Environment Variables

CLI Reference

Overview

Directory Structure

The `.forge/` Directory

Configuration Files

Worktrees Directory

Git Worktrees Explained

What Are Worktrees?

Why Worktrees?

How It Works

Database Schema

Projects Table

Tasks Table

Attempts Table

Backup & Restore

Backing Up Forge Data

Restoring From Backup

Cleanup & Maintenance

Clean Old Worktrees

Clean Old Logs

Compact Database

Complete Clean

Multi-User Scenarios

Personal Projects

Team Projects

Shared Forge Instance (Advanced)

Best Practices

Troubleshooting

Next Steps