Tahti - Autonomous Orchestrator

Tahti (Finnish for "star" ⭐) is an autonomous orchestrator for parallel feature development with isolated workspaces and CI integration.

Features

• 🤖 Parallel Development - Run multiple bots on different features simultaneously
• 📦 Isolated Workspaces - Each bot works in its own repository clone
• 🔧 Auto Setup - Automatic dependency installation and setup scripts (hooks, init) after clone
• ✅ CI Integration - Wait for pipeline completion before moving on
• 🎯 Single Feature Focus - Bots stop after completing one feature
• 🛑 Self-Termination - Bots can gracefully stop when work is done
• 🔒 MCP Server - Secure API through Model Context Protocol
• 🔄 Hot Reload - Update MCP server without disconnecting clients (auto git pull every 5min)
• 🎯 Workspace Scope - Operations default to current workspace, preventing accidents
• 🔄 MR Timeout Retry - Automatic retry with fallback to browser URL for manual creation
• 📝 TODO Sync to MR - Automatically syncs TODO content to merge request description
• 🖥️ K9s-style TUI - Terminal UI for live monitoring and bot control
• ⚡ Lazy Clone - Instant job creation (< 1s) with deferred repository cloning
• 🐛 Dev Issue System - Automated bug reporting and job creation from user-reported issues
• 🧠 Intelligent Model Selection - Automatic AI model selection based on task complexity
• 🏥 Workspace Health Daemon - Self-healing system that auto-fixes stale bot states and workspace issues
• 📊 Hierarchical Logging - Job cycle logs, workspace logs, and infrastructure logs for easy debugging

Usage

All features are accessible through the unified tahti MCP tool:

// Use tahti for all operations ⭐
tahti({ resource: "job", action: "list", workspace: "infra" })
tahti({ resource: "bot", action: "start", workspace: "...", task: "..." })

📚 API Reference: For detailed documentation of all resources and actions, see docs/reference/api/API_V2_COMPREHENSIVE_GUIDE.md. All 59 actions across 11 resource types are documented with examples.

📚 Migration Guide: If you were using legacy standalone tools (list_workspace_files, start_bot, etc.), see docs/reference/guides/MIGRATION_TO_TAHTI_API.md for a complete mapping to the unified API.

Hot Reload (Zero-Downtime Updates)

Update MCP server code without disconnecting AI agent:

# Start MCP with hot-reload (recommended)
npm run mcp

# Auto-pulls from git every 5 minutes
# Or trigger manually:
tahti({ resource: "system", action: "reload" })

How it works:

1. Proxy monitors git remote every 5 minutes
2. Detects code changes (commit SHA comparison)
3. Runs git pull automatically
4. Restarts worker process seamlessly
5. AI agent stays connected (no reconnect needed!)

See: docs/internal/architecture/hot-reload-architecture.md

Lazy Clone (Fast Job Creation)

Create jobs instantly without waiting for repository clones:

// Traditional: 30-60s (clones immediately)
tahti({
  resource: "job",
  action: "create",
  projectPath: "kotocoop/software/koto-tracking",
  jobName: "fix-bug-123",
  taskDescription: "Fix authentication bug"
})

// Lazy clone: < 1s (clones when bot starts)
tahti({
  resource: "job",
  action: "create",
  projectPath: "kotocoop/software/koto-tracking",
  jobName: "fix-bug-123",
  taskDescription: "Fix authentication bug",
  shallowClone: true        // Use --depth=1 (default)
})

Benefits:

• 60x faster job creation (30-60s → < 1s)
• Queue multiple jobs instantly
• No wasted bandwidth if job cancelled
• Shallow clones save ~50% disk space

How it works:

1. createJobFromGitLab saves metadata without cloning
2. Bot manager calls cloneJobIfNeeded() when starting
3. Repository cloned with --depth=1 (if shallowClone: true)
4. Feature branch created and merged automatically

Intelligent Model Selection (Cost Optimization)

Automatically selects the most cost-effective AI model based on task complexity analysis:

// Complexity is analyzed from TODO content
// Model is automatically selected and passed to Copilot
tahti({
  resource: "bot",
  action: "start",
  workspace: "auto-bots/koto-tracking/fix-typo",
  task: "Fix typo in login form"
  // No manual model selection needed!
  // Bot will use gpt-4.1-mini for this trivial task
})

Complexity Levels & Model Selection:

• Trivial → gpt-4.1-mini ($0.05/run): Typo fixes, version bumps, simple renames
• Simple → gpt-4.1 ($0.15/run): Test additions, doc updates, linting fixes
• Medium → gpt-4.1 ($0.25/run): Generic tasks, 5+ files affected
• Complex → gpt-5 ($0.50/run): Architecture work, migrations, 10+ files

Analysis Indicators:

• Task description keywords (fix, refactor, migrate, etc.)
• Number of files mentioned in TODO
• Number of tasks/checkboxes
• Estimated lines of code
• Historical job complexity (if available)

Override Options:

// Force specific model (stored in job metadata)
{
  "forceModel": "claude-sonnet-4.5",
  "minComplexity": "medium"  // Don't use models cheaper than medium
}

Benefits:

• 60-80% cost savings on simple tasks (using cheaper models)
• Better quality on complex tasks (using advanced models)
• Automatic optimization - no manual configuration needed
• Transparent - model selection logged with reasoning

How it works:

1. Bot manager reads TODO content on startup
2. Complexity analyzer scans for patterns and indicators
3. Model selector chooses appropriate model based on complexity
4. Model passed to Copilot via COPILOT_MODEL environment variable
5. Selection and reasoning saved to job metadata

TODO Sync to MR Description

Automatically keeps merge request descriptions synchronized with TODO content during work:

// TODO content is automatically synced to MR description
// Both when MR is created and when TODO is updated

// Configuration (default: enabled)
{
  "syncTodoToMR": true  // Set to false to disable sync
}

How it works:

1. When MR is created, TODO content is included in description
2. When bot updates TODO during work, MR description is updated automatically
3. Sync can be disabled per-job via config.json
4. Uses GitLab API directly (koto-gitlab MCP integration pending)

Benefits:

• Context Preservation - MR description always reflects current work plan
• Team Visibility - Reviewers see up-to-date task list and rationale
• Automatic - No manual effort required
• Configurable - Can be disabled if not wanted

Location: .tahti/{repo}/{job}/config.json

Architecture

tahti/
├── bot-manager/          # Workspace and bot orchestration
├── mcp-server/           # Model Context Protocol server
├── tui-client/           # K9s-style terminal UI
├── configs/              # Bot instruction templates
└── docs/                 # Documentation

Directory Structure

New structure (v2.0+):

~/workspaces/                           # Workspace collection root
├── {workspace}/                        # Workspace (e.g., "auto-bots")
│   ├── .tahti/                    # Metadata (outside git repos)
│   │   └── {repo}/                     # Repository
│   │       └── {job}/                  # Job metadata & logs
│   │           ├── metadata.json       # Job information
│   │           ├── bot.log             # Bot execution log
│   │           └── bot-state.json      # Bot runtime state
│   └── {repo}/                         # Repository clone
│       └── {job}/                      # Job working directory

Path format: workspace/repo/job
Example: auto-bots/tahti/fix-bug-123

Background Daemons

The MCP proxy runs three background daemons for autonomous operation:

1. Monitor Daemon - Continuously polls monitors and auto-creates jobs when conditions are met
2. Recurring Scheduler - Starts jobs periodically (e.g., every 30 minutes)
3. Health Daemon (NEW) - Self-healing system that automatically:
   • Cleans stale .bot-state.json files from crashed bots
   • Enables auto-merge on open MRs (future)
   • Cleans up finished jobs (future)

See: docs/internal/architecture/WORKSPACE_HEALTH.md

Configuration

Environment Variables

WORKSPACE_ROOT - ⚠️ DEPRECATED - Use .workspaces marker file instead (see Workspace Discovery below)

The system now auto-detects workspaces using a .workspaces marker file. For backward compatibility, you can still set:

export WORKSPACE_ROOT=~/my-workspaces  # Legacy - not recommended

GITLAB_TOKEN - GitLab API token for operations (optional, uses glab if not set)

export GITLAB_TOKEN=glpat-xxxxx

Workspace Discovery

The system uses a .workspaces marker file to automatically detect the workspace collection root:

# Create a marker file in your workspaces directory
cd ~/workspaces
touch .workspaces

# Now all workspace operations will auto-detect this directory
# No need to set WORKSPACE_ROOT!

Directory Structure:

~/workspaces/              ← Create .workspaces marker here
├── .workspaces           ← Marker file (empty)
├── auto-bots/            ← Individual workspace
│   └── .tahti/      ← Job metadata
├── kotoverstas/
│   └── .tahti/
└── my-workspace/
    └── .tahti/

The system searches upward from the current directory to find the .workspaces marker. This allows you to:

• Run commands from any subdirectory
• Use multiple workspace collections
• No environment variables needed!

GitHub Token

Bots need a GitHub token to authenticate. The token is automatically read from MCP client configuration (e.g., GitHub Copilot CLI):

• Auto-detected from: ~/.config/github-copilot/apps.json (for Copilot)
• Workspace settings: .tahti/settings.json in your workspace directory

// .tahti/settings.json (optional)
{
  "githubToken": "gho_xxxxx...",
  "jobQueue": {
    "maxConcurrentJobs": 5,
    "maxConcurrentCopilotProcesses": 5
  }
}

Note: If the token in apps.json is outdated, either:

1. Run gh auth login to refresh
2. Set githubToken manually in orchestrator.json

Resource Limits

The system automatically prevents resource exhaustion by limiting concurrent jobs and Copilot processes:

Default Limits:

• maxConcurrentJobs: 5 (maximum parallel bots)
• maxConcurrentCopilotProcesses: 5 (respects GitHub API limits)

Automatic Enforcement:

• startMultipleJobs checks capacity before starting jobs
• Recurring scheduler skips iterations when at capacity
• Jobs queued when resources unavailable

Monitoring:

// Check current resource usage
tahti({
  resource: "resource",
  action: "get_usage",
  workspace: "auto-bots"  // Optional
})

// Returns:
{
  canStart: true,
  reason: "Capacity available (2/5 jobs, 3/5 Copilot processes)",
  stats: {
    runningJobs: 2,
    maxJobs: 5,
    copilotProcesses: 3,
    maxCopilotProcesses: 5,
    availableSlots: 3,
    availableCopilotSlots: 2
  }
}

Configuration: Edit .tahti/settings.json in your workspace:

{
  "jobQueue": {
    "maxConcurrentJobs": 3,              // Reduce for smaller systems
    "maxConcurrentCopilotProcesses": 3   // Match GitHub account limits
  }
}

Per-Bot Resource Limits:

Control individual bot resource consumption:

orchestrator_start_bot({
  workspace: "auto-bots/my-repo/feature",
  task: "Add new feature",
  maxRunTime: 3600,           // Max runtime in seconds (0 = unlimited)
  maxPremiumRequests: 50,     // Max premium API requests (0 = unlimited)
  maxTotalTokens: 1000000     // Max total tokens (0 = unlimited)
})

Bot stops gracefully when any limit is exceeded. All limits are optional and default to 0 (unlimited).

Workspace Settings

Configure workspace-level settings using the tahti API:

// Set a workspace setting
tahti({
  resource: "workspace",
  action: "set_setting",
  workspace: "my-workspace",
  key: "worker_inactivity_timeout_minutes",
  value: 10
})

// Get a workspace setting
tahti({
  resource: "workspace",
  action: "get_setting",
  workspace: "my-workspace",
  key: "worker_inactivity_timeout_minutes"
})

// List all settings for a workspace
tahti({
  resource: "workspace",
  action: "list_settings",
  workspace: "my-workspace"
})

Available Workspace Settings:

| Setting | Type | Default | Description | |---------|------|---------|-------------| | worker_inactivity_timeout_minutes | number | 5 | MCP worker inactivity timeout before graceful shutdown | | default_job_timeout | number | 3600 | Default timeout for jobs in seconds | | auto_merge_cooldown | number | 20 | Cooldown period in minutes before allowing another merge | | max_concurrent_jobs | number | 3 | Maximum number of jobs that can run concurrently | | default_cycle_duration | number | 60 | Default duration of a bot cycle in seconds | | default_max_cycles | number | 5 | Default maximum number of cycles a bot should run | | scheduler_interval | number | 10 | Interval in minutes for scheduler checks | | priority_boost_on_failure | boolean | true | Whether to boost priority when a job fails |

Workspace Configuration

Workspaces are automatically detected via .workspace marker files. No manual creation needed - just create jobs and workspaces are auto-configured:

// Jobs automatically create and configure workspaces
tahti({
  resource: "job",
  action: "create",
  projectPath: "kotocoop/software/koto-tracking",
  jobName: "my-feature"
})
// Workspace is auto-created at detection time

Quick Start

Using TUI (Recommended for Monitoring)

# Install dependencies
npm install

# Start the TUI client
npm run tui

# Navigate with arrow keys, press 'h' for help

Command Line

# Install globally
npm install -g tahti

# This installs three binaries:
# - tahti (CLI for bot management)
# - tahti-tui (Terminal UI for monitoring)
# - tahti-mcp (MCP server for integration)

# Setup workspace collection marker
cd ~/bot-workspaces
touch .workspaces

# Configure main repo
export MAIN_REPO=~/git/your-project

# Run bot on a feature
tahti run fix-bug-123 "Fix storage calculation" 60

# Check status
tahti status

# Wait for CI
tahti wait-ci fix-bug-123

Or install from source:

# Clone repository
git clone https://kotocoop.org/gitlab/kotocoop/software/tahti.git
cd tahti

# Install dependencies
npm install

# Use npm scripts
npm run mcp      # Start MCP server (stdio mode)
npm run mcp -- --socket  # Start MCP server with Unix socket support
npm run tui      # Start TUI client
npm start        # Start bot manager

Unix Socket Mode

The MCP server can optionally listen on a Unix domain socket for local TUI/CLI clients:

# Start with socket support
npm run mcp -- --socket

# Socket created at: .tahti/tahti-mcp.sock
# PID file created at: .tahti/tahti-mcp.pid

Features:

• Multiple concurrent socket connections
• Works alongside stdio transport (Copilot stays connected)
• Graceful cleanup on shutdown
• Socket and PID files auto-removed on exit

Standalone Bundle (Portable Deployment)

Create a standalone bundle that includes both autonomous-orchestrator and koto-gitlab MCPs in a single portable package:

# Build standalone bundle
npm run build:sea

# Output:
# - dist/tahti-mcp - Standalone runner script (requires Node.js)
# - dist/bundle/ - Bundled code (1.8MB)
# - dist/tahti-mcp-binary - SEA binary (if Node supports it)

Features:

• ✅ Single command build - All dependencies bundled with @vercel/ncc
• ✅ ES module compatible - Automatic __dirname/__filename polyfills
• ✅ 2 MCPs in 1 - Includes both orchestrator + koto-gitlab tools
• ✅ Portable - Copy dist/ folder to any system with Node.js
• ⚠️ SEA binary - Optional, requires Node.js with --experimental-sea-config

Usage:

# Run bundled version (requires Node.js on system)
./dist/tahti-mcp

# Or run directly
node dist/bundle/index.mjs

# Install to system (recommended)
sudo ./scripts/install.sh

# Or install to user directory (no sudo needed)
./scripts/install.sh ~/.local/bin

Distribution:

# Package for distribution
tar czf tahti-mcp-bundle.tar.gz dist/

# On target system
tar xzf tahti-mcp-bundle.tar.gz
cd dist
./tahti-mcp

CI/CD Integration:

# .gitlab-ci.yml
build:
  script:
    - npm install
    - npm run build:sea
  artifacts:
    paths:
      - dist/

Single Executable Application (SEA): The build script attempts to create a native binary with no Node.js dependency, but this requires Node.js built with --experimental-sea-config support. Most systems don't have this yet, so the bundled version is the recommended approach.

See: scripts/build-sea.sh

MCP Server

The MCP server provides safe, scoped access to:

• Workspace-scoped operations - All tools default to current workspace from $PWD
• Git operations (clone, branch, commit, push)
• CI status checking (GitLab/GitHub)
• Test execution
• File operations (read, write in workspace only)
• Multi-repo support - Clone and manage multiple repos in one job
• Job scheduling - Schedule delayed bot starts for future execution
• Built-in documentation - Request help via MCP prompts
• Workspace context resources - Access workspace overview, job history, and patterns

Safety: Operations are automatically scoped to your current workspace, preventing accidental operations on other workspaces. See Workspace Scope Detection for details.

MCP Resources

The server exposes workspace context as MCP resources for automatic access:

workspace://context/{workspace_name}

Workspace Context Resource provides:

• 📊 Workspace overview and repository list
• 📜 Job history (active and archived jobs)
• 🔍 Common job patterns and themes
• 💡 Project information and detected technologies
• 📚 Practical tips and common commands

Usage in Copilot: The workspace context is automatically available as an MCP resource. Bots are reminded to read it in their work cycle prompt. The resource:

• Auto-generates from workspace structure if WORKSPACE_CONTEXT.md doesn't exist
• Reads existing WORKSPACE_CONTEXT.md if present
• Updates automatically as jobs are created/archived

Context is generated automatically - no manual tools needed.

Getting Help

Access comprehensive documentation via the MCP tool:

// System overview and core concepts
orchestrator_get_documentation({ topic: "overview" })

// Job lifecycle and management
orchestrator_get_documentation({ topic: "jobs" })

// Bot execution and control
orchestrator_get_documentation({ topic: "bots" })

// Event monitoring and automation
orchestrator_get_documentation({ topic: "monitors" })

// Automated job processing
orchestrator_get_documentation({ topic: "recurring-schedules" })

// Complete tool reference
orchestrator_get_documentation({ topic: "api-reference" })

Or use legacy prompts for system instructions:

// Complete system instructions
prompt("instructions")

// Terminology guide (workspace/job/worker)
prompt("terminology")

// Usage examples
prompt("examples")

// WORKSPACE.md template and best practices
prompt("workspace_template")

WORKSPACE.md - Project Context

Every job automatically includes a WORKSPACE.md file with:

• 🎯 Project overview and technology stack
• 🧪 Testing workflow (language-specific commands)
• 📝 Git conventions and commit format
• ✅ Critical ALWAYS rules
• ❌ Critical NEVER rules
• 🛑 Self-termination criteria

🚨 Bots must read WORKSPACE.md before starting any work!

No broad filesystem or shell access needed.

Container Deployment

The orchestrator MCP server is available as a Docker image for easy deployment:

# Pull from registry
docker pull registry-build.kotocoop.org/autonomous-orchestrator:latest

# Run with workspace volume
# The .workspaces marker file should be in the mounted volume
docker run -d \
  -v /path/to/workspaces:/workspaces \
  registry-build.kotocoop.org/autonomous-orchestrator:latest

# Or build locally
docker build -t autonomous-orchestrator .
docker run -d -v $PWD/workspaces:/workspaces autonomous-orchestrator

# Note: Ensure .workspaces marker exists in your workspaces directory:
# touch /path/to/workspaces/.workspaces

Environment Variables

• WORKSPACE_ROOT - ⚠️ DEPRECATED - Use .workspaces marker file instead
• NODE_ENV - Node environment (default: production)

See DEPLOYMENT.md for detailed deployment instructions.

Job Scheduling

Schedule bots to start at a later time:

// Schedule a bot to start in 30 minutes
tahti({
  resource: "schedule",
  action: "create",
  type: "one-time",
  workspace: "my-project/feature-123",
  task: "Implement user authentication",
  delayMinutes: 30,
  maxCycles: 5,
  cycleInterval: 60
})

// List all scheduled jobs
tahti({
  resource: "schedule",
  action: "list"
})

// Cancel a scheduled job
tahti({
  resource: "schedule",
  action: "cancel",
  scheduleId: "schedule_..."
})

Perfect for:

• Scheduling overnight bot runs
• Delaying start until after meetings
• Batch scheduling multiple bots with time gaps

Recurring Job Execution

Run jobs automatically on a repeating schedule:

// Start recurring execution: 2 jobs every 30 minutes
tahti({
  resource: "schedule",
  action: "create",
  type: "recurring",
  workspacePath: "/home/user/workspaces/koto-tracking-ws",
  jobCount: 2,           // Run 2 jobs per interval
  intervalMinutes: 30,   // Every 30 minutes
  maxCycles: 5,          // 5 cycles per bot run
  cycleInterval: 60      // 60 seconds per cycle
})

// List all recurring schedules
tahti({
  resource: "schedule",
  action: "list"
})

// Stop a recurring schedule
tahti({
  resource: "schedule",
  action: "stop",
  recurringId: "recurring-1"
})

How it works:

• Jobs are selected alphabetically from .tahti/{workspace}/ directory
• First N jobs are started in parallel every interval (fire-and-forget)
• Scheduler doesn't wait for jobs to complete before next iteration
• Monitor with tahti({ resource: "bot", action: "status", workspace: "..." })
• Perfect for continuous development on multiple features
• Schedules persist even if MCP server restarts

Use Cases

1. Feature Development - Each feature in isolated workspace
2. Bug Fixes - Parallel bug fixing with TDD
3. Test Coverage - Add tests for uncovered code
4. Refactoring - Safe isolated refactoring

Dev Issue Reporting System

Reusable system for automated bug reporting and job creation. Developers can report UI issues with rich context (screenshots, selectors, console errors) and the system automatically creates fix jobs.

Components:

• 📝 Frontend widget for reporting issues
• 🔌 Backend API for storing issues
• 🔍 Monitor script for fetching and consolidating issues
• 🤖 Job creator for automated fix job creation

Quick Start:

# Monitor issues from API
API_URL=http://localhost:8000 ./scripts/dev-issue-monitor.py

# Create jobs from reported issues
PROJECT_PATH=kotocoop/software/your-project \
./scripts/dev-issue-job-creator.py

Documentation: DEV_ISSUE_SYSTEM.md

Safety Features

• ✅ Workspace isolation (no cross-contamination)
• ✅ Single feature constraint (no scope creep)
• ✅ CI gating (must pass before completion)
• ✅ Time limits (prevent runaway bots)
• ✅ Self-termination (bots stop when no work remains)
• ✅ MCP sandboxing (limited API surface)

Documentation

• Complete Documentation - Full documentation index
• MCP Server Architecture
• Multi-Repo Jobs
• Logging Architecture - Job cycle logs, workspace logs, and infrastructure logs
• Examples

License

Tahti is source-available software licensed under Apache 2.0 with Commons Clause restriction.

What This Means

• ✅ Free for small organizations: Startups, non-profits, and individual developers can use Tahti at no cost
• ✅ View and modify source: Full access to source code for learning and contribution
• ✅ Fork and contribute: Community contributions welcome under our CLA
• ❌ Commercial restrictions: Large organizations (revenue > €10M or > 100 developers) need a commercial license to sell Tahti-based services

License Files

• LICENSE - Apache 2.0 full text
• COMMONS_CLAUSE - Commercial use restrictions and who needs a license
• CLA.md - Contributor License Agreement (required for contributions)
• TRADEMARK_POLICY.md - "Tahti" trademark usage policy
• NOTICE - Copyright and third-party component notices

Commercial Licensing

For commercial licensing inquiries (enterprise features, priority support, SLA):

• Contact: [contact information to be added]
• See COMMONS_CLAUSE for details

Contributing

By contributing to this project, you agree to the Contributor License Agreement. Use git commit -s to sign off your commits.

See CONTRIBUTING.md for contribution guidelines.

Development

• Branch Workflow - Guidelines for main vs feature branches
• MCP Restart Guide - When to restart MCP server
• Testing Guide - Testing strategy and tools
• Testing Improvements - Recent stability improvements

Getting Started

After cloning:

# Install dependencies
npm install

# Install git hooks
./install-hooks.sh

# Run tests
npm test
npm run test:all

Testing

npm test              # Unit and integration tests
npm run test:all      # All tests (unit + integration)
npm run test:e2e      # E2E tests (separate subproject)
npm run test:stress   # Stress test (1 min)
npm run health        # Check running servers

E2E tests are located in the e2e-tests/ directory and run independently from the main test suite.

Git hooks automatically run tests before each commit.

Code Quality Tools

Static analysis tools help prevent bugs and maintain code quality:

npm run lint              # Check code with ESLint
npm run lint:fix          # Auto-fix ESLint issues
npm run format            # Format code with Prettier
npm run format:check      # Check formatting
npm run check-duplicates  # Detect code duplication
npm run quality           # Run all quality checks

Key Features:

• ESLint: Enforces complexity limits, function length, and custom rules
• Prettier: Consistent code formatting
• JSCPD: Detects duplicate code
• Custom Rules: Prevents manual .tahti path construction

See Code Quality Guide for detailed documentation.

Statistics Reporting

Analyze bot run statistics with the bot-stats.js reporting tool. View performance metrics, model usage, success rates, and productivity trends from your bot runs.

Quick Examples

# Last 24 hours summary
node scripts/bot-stats.js --last 24h

# Last 8 hours (default reporting period)
node scripts/bot-stats.js --last 8h

# Last 7 days
node scripts/bot-stats.js --last 7d

# Specific date range
node scripts/bot-stats.js --range "2026-01-20" "2026-01-22"

# Model comparison
node scripts/bot-stats.js --by-model --last 24h

# Productivity metrics
node scripts/bot-stats.js --productivity --last 7d

# Failure analysis
node scripts/bot-stats.js --failures --last 24h

# Filter by repository or job
node scripts/bot-stats.js --repo tahti --last 7d
node scripts/bot-stats.js --job check-mr-before-loop

Output Formats

Export reports in different formats:

# Console output (default, colored and formatted)
node scripts/bot-stats.js --last 24h

# JSON for programmatic use
node scripts/bot-stats.js --last 24h --format json

# CSV for spreadsheets
node scripts/bot-stats.js --last 24h --format csv

# Markdown for documentation
node scripts/bot-stats.js --last 24h --format markdown

Available Options

• --last <duration> - Filter by last N hours/days (e.g., 8h, 24h, 7d)
• --since <date> - Filter entries since date (YYYY-MM-DD)
• --range <start> <end> - Filter by date range
• --by-model - Group statistics by model
• --job <name> - Filter by job name
• --repo <name> - Filter by repository name
• --productivity - Show productivity metrics
• --failures - Show failure analysis
• --format <type> - Output format (console, json, csv, markdown)
• --file <path> - Custom path to bot_runs.jsonl

Reports Include

• Summary: Total runs, cycles, success rate, average duration
• Model Usage: Distribution across different AI models with performance metrics
• Job Activity: Most active jobs with cycle counts
• Repository Activity: Breakdown by repository
• Work Types: Distribution of feature/bugfix/refactor/test work
• Productivity: Runs per hour, cycles per hour, efficiency trends
• Failures: Analysis of failure patterns by outcome, job, and model

Data Source

Statistics are collected from .tahti/statistics/bot_runs.jsonl which tracks every bot run with:

• Timestamp, workspace, repository, job name
• Model used and cycles consumed
• Duration and outcome (success/failed/ci_failed/timeout)
• Work type tags and subtask information

See docs/internal/features/STATISTICS_REPORTING_TOOL.md for complete specification and technical details.

Migration from v1.x

If you have existing workspaces in the old structure (~/autonomous-workspaces/{workspace}/{job}), migrate them to the new structure:

# Run migration script
./migrate-workspace-structure.sh

The script will:

1. Create new ~/workspaces/ directory
2. Scan each workspace for jobs
3. Group jobs by repository
4. Move to new structure: workspace/repo/job
5. Create .tahti/ metadata directories
6. Preserve all TODO files and git history
7. Keep old structure intact for verification

After migration:

• Review the new structure in ~/workspaces/
• Create .workspaces marker file: touch ~/workspaces/.workspaces
• Remove old ~/autonomous-workspaces/ when satisfied

The migration is safe and preserves all data. Old structure remains until you manually remove it.

GitLab Tools (NEW)

Recommended: Use koto-gitlab MCP for GitLab operations.

The autonomous-orchestrator has legacy orchestrator_gitlab_* tools, but these are deprecated. Use the shared koto-gitlab MCP instead:

Available in koto-gitlab MCP:

• git_create_merge_request - Create MR with auto-detected target branch
• git_merge_request_status - Check MR status
• git_safe_push - Safe push with MR creation
• git_create_feature_branch - Create feature branch
• gitlab_search_projects - Search GitLab projects
• gitlab_get_branches - Get project branches

Setup koto-gitlab:

# Install
cd ~/git
git clone [email protected]:kotocoop/koto-gitlab-mcp.git
cd koto-gitlab-mcp
npm install

# Add to MCP config (~/.config/Code/User/mcp.json)
{
  "servers": {
    "koto-gitlab": {
      "command": "/home/user/.local/bin/koto-gitlab-mcp.sh",
      "args": []
    }
  }
}

Migration Guide:

• orchestrator_gitlab_create_mr → git_create_merge_request (koto-gitlab)
• orchestrator_gitlab_get_mr_status → git_merge_request_status (koto-gitlab)
• Use git_safe_push for automatic push + MR creation

See: https://gitlab.com/kotocoop/koto-gitlab-mcp