Project Commands

Overview

Forge projects are managed through the Web UI. Each project represents a codebase with its own task board, git repository, and configuration. Projects are automatically created when you first launch Forge in a directory.

Project Initialization

When you run Forge for the first time in a directory:

cd your-project
automagik-forge

Forge automatically:

Detects if it’s a git repository
Creates .forge/ directory with configuration
Initializes SQLite database
Generates unique project ID
Opens web UI at http://localhost:3000

Project Structure

your-project/
├── .forge/
│   ├── config.json          # Project configuration
│   ├── db.sqlite            # Task database
│   ├── worktrees/           # Git worktrees for tasks
│   └── logs/                # Execution logs
├── .git/                    # Git repository
└── your-code/               # Your project files

Project Configuration

The .forge/config.json file stores project settings:

{
  "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My Awesome Project",
  "repository": {
    "type": "git",
    "remote": "https://github.com/owner/repo.git",
    "default_branch": "main"
  },
  "github": {
    "enabled": true,
    "owner": "owner",
    "repo": "repo",
    "token_encrypted": "..."
  },
  "worktrees": {
    "enabled": true,
    "base_path": "./.forge/worktrees",
    "cleanup_on_exit": true,
    "max_concurrent": 5
  },
  "executors": {
    "default": "claude-code",
    "enabled": [
      "claude-code",
      "cursor-cli",
      "gemini",
      "codex"
    ]
  },
  "preferences": {
    "auto_cleanup_worktrees": true,
    "stream_logs": true,
    "theme": "dark"
  }
}

GitHub Integration

Connect your project to GitHub for OAuth and issue sync:

Setup via Web UI

Open Settings

# Start Forge
automagik-forge

# Navigate to: Settings → GitHub Integration

Authenticate

Click “Connect GitHub”

Redirects to GitHub OAuth
Authorize Forge app
Returns with token

Select Repository

Choose repository from dropdown
Forge syncs repo metadata
Configuration saved

Verify Connection

Green checkmark appears
Repository name displayed
Issue sync enabled

Manual Configuration

Edit .forge/config.json:

{
  "github": {
    "enabled": true,
    "owner": "your-username",
    "repo": "your-repo",
    "client_id": "your-github-oauth-app-id"
  }
}

Then authenticate via device flow:

# Forge will prompt for GitHub authentication
automagik-forge

Project REST API

Interact with projects programmatically:

List Projects

curl http://localhost:5000/api/projects

Response:

{
  "projects": [
    {
      "id": "uuid-here",
      "name": "My Project",
      "path": "/home/user/my-project",
      "repository": {
        "remote": "https://github.com/owner/repo",
        "branch": "main"
      },
      "task_count": 42,
      "created_at": "2024-10-31T10:00:00Z",
      "updated_at": "2024-10-31T15:30:00Z"
    }
  ]
}

Get Project Details

curl http://localhost:5000/api/projects/{project-id}

Update Project

curl -X PATCH http://localhost:5000/api/projects/{project-id} \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Project Name",
    "default_executor": "gemini"
  }'

Delete Project

# Warning: This deletes all tasks and configuration
curl -X DELETE http://localhost:5000/api/projects/{project-id}

MCP Project Tools

When running in MCP mode, use these tools from AI agents:

list_projects
get_project (Advanced Mode)
create_project (Advanced Mode)
update_project (Advanced Mode)

List all projects

{
  "tool": "list_projects",
  "arguments": {}
}

Returns array of all Forge projects.

Get project detailsAvailable in --mcp-advanced mode only.

{
  "tool": "get_project",
  "arguments": {
    "project_id": "uuid-here"
  }
}

Create new projectAvailable in --mcp-advanced mode only.

{
  "tool": "create_project",
  "arguments": {
    "name": "New Project",
    "path": "/path/to/project",
    "repository_url": "https://github.com/owner/repo"
  }
}

Update project settingsAvailable in --mcp-advanced mode only.

{
  "tool": "update_project",
  "arguments": {
    "project_id": "uuid-here",
    "name": "Updated Name",
    "default_executor": "claude-code"
  }
}

Project Settings

Configure project behavior via Web UI:

General Settings

Project Name: Display name
Default Branch: Git branch for new worktrees
Default Executor: AI agent for new tasks
Auto-cleanup: Remove worktrees after merge

GitHub Settings

OAuth Token: GitHub authentication
Issue Sync: Auto-create tasks from issues
PR Integration: Link tasks to pull requests
Webhook: Real-time updates

Executor Settings

Configure available AI agents:

Claude Code
Cursor CLI
Gemini
OpenAI Codex

{
  "executors": {
    "claude-code": {
      "enabled": true,
      "api_key_env": "ANTHROPIC_API_KEY",
      "model": "claude-3-5-sonnet-20241022",
      "max_tokens": 8192
    }
  }
}

{
  "executors": {
    "cursor-cli": {
      "enabled": true,
      "cli_path": "/usr/local/bin/cursor",
      "args": ["--headless"]
    }
  }
}

{
  "executors": {
    "gemini": {
      "enabled": true,
      "api_key_env": "GOOGLE_AI_API_KEY",
      "model": "gemini-2.0-flash-exp"
    }
  }
}

{
  "executors": {
    "codex": {
      "enabled": true,
      "api_key_env": "OPENAI_API_KEY",
      "model": "gpt-4"
    }
  }
}

Worktree Settings

{
  "worktrees": {
    "enabled": true,
    "base_path": "./.forge/worktrees",
    "cleanup_on_exit": true,
    "max_concurrent": 5,
    "branch_prefix": "forge/task-",
    "auto_delete_merged": true
  }
}

Multi-Project Workflow

Work with multiple projects:

Project 1 - Frontend

cd ~/projects/frontend-app
automagik-forge --port 3000 --backend-port 5000

Opens at http://localhost:3000

Project 2 - Backend

cd ~/projects/backend-api
automagik-forge --port 3001 --backend-port 5001

Opens at http://localhost:3001

Project 3 - Mobile

cd ~/projects/mobile-app
automagik-forge --port 3002 --backend-port 5002

Opens at http://localhost:3002

Each project runs independently with its own:

Task board
Database
Worktrees
Configuration

Project Export/Import

Export Project

# Via API
curl http://localhost:5000/api/projects/{project-id}/export > project-backup.json

Exports:

Project configuration
All tasks and attempts
Execution history
Labels and metadata

Import Project

# Via API
curl -X POST http://localhost:5000/api/projects/import \
  -H "Content-Type: application/json" \
  -d @project-backup.json

Project Migration

Moving a project to a new location:

Backup Current Project

# Export project data
curl http://localhost:5000/api/projects/{id}/export > backup.json

# Copy .forge directory
cp -r .forge/ .forge-backup/

Move Repository

# Move to new location
mv ~/old-location ~/new-location
cd ~/new-location

Update Configuration

# Edit .forge/config.json
# Update any absolute paths
# Verify repository settings

Verify and Launch

# Start Forge
automagik-forge

# Verify tasks and settings loaded

Project Analytics

View project statistics via Web UI or API:

curl http://localhost:5000/api/projects/{project-id}/analytics

Metrics:

Total tasks created
Tasks by status
Tasks by executor
Average completion time
Success rate per executor
Active worktrees
Repository activity

Common Issues

Project ID Not Found

Symptom: MCP tools return “Project not found”Solution:

# Get project ID from Web UI
# Settings → Project Info → Project ID

# Or from config
cat .forge/config.json | grep project_id

# Update MCP configuration with correct ID

GitHub Authentication Failed

Symptom: “GitHub OAuth failed” errorSolution:

# 1. Verify GitHub OAuth app settings
# 2. Check redirect URL: http://localhost:3000/auth/callback
# 3. Re-authenticate via Web UI
# 4. Or set GITHUB_CLIENT_ID env var

Multiple Projects Conflict

Symptom: Port already in useSolution:

# Use different ports for each project
automagik-forge --port 3001 --backend-port 5001

Worktree Directory Too Large

Symptom: .forge/worktrees/ consuming disk spaceSolution:

# Clean up old worktrees
# Via Web UI: Settings → Cleanup → Remove Old Worktrees

# Or enable auto-cleanup in config.json
{
  "worktrees": {
    "auto_delete_merged": true,
    "cleanup_on_exit": true
  }
}

Next Steps

Task Commands

Manage tasks within projects

Config Commands

Configure project settings

Projects API

Complete API reference

GitHub Integration

Set up GitHub OAuth

Getting Started

Learn

Configuration

Reference

Troubleshooting

Overview

Project Initialization

Project Structure

Project Configuration

GitHub Integration

Setup via Web UI

Manual Configuration

Project REST API

List Projects

Get Project Details

Update Project

Delete Project

MCP Project Tools

Project Settings

General Settings

GitHub Settings

Executor Settings

Worktree Settings

Multi-Project Workflow

Project Export/Import

Export Project

Import Project

Project Migration

Project Analytics

Common Issues

Next Steps

Task Commands

Config Commands

Projects API

GitHub Integration

​Overview

​Project Initialization

​Project Structure

​Project Configuration

​GitHub Integration

​Setup via Web UI

​Manual Configuration

​Project REST API

​List Projects

​Get Project Details

​Update Project

​Delete Project

​MCP Project Tools

​Project Settings

​General Settings

​GitHub Settings

​Executor Settings

​Worktree Settings

​Multi-Project Workflow

​Project Export/Import

​Export Project

​Import Project

​Project Migration

​Project Analytics

​Common Issues

​Next Steps

Task Commands

Config Commands

Projects API

GitHub Integration

Overview

Project Initialization

Project Structure

Project Configuration

GitHub Integration

Setup via Web UI

Manual Configuration

Project REST API

List Projects

Get Project Details

Update Project

Delete Project

MCP Project Tools

Project Settings

General Settings

GitHub Settings

Executor Settings

Worktree Settings

Multi-Project Workflow

Project Export/Import

Export Project

Import Project

Project Migration

Project Analytics

Common Issues

Next Steps