mirror of
https://github.com/coleam00/Archon
synced 2026-04-21 21:47:53 +00:00
a28e695aee
* feat: Phase 3 - Database abstraction layer and CLI isolation Part A: Database Abstraction Layer - Add IDatabase interface supporting PostgreSQL and SQLite - Create PostgresAdapter wrapping pg Pool with same interface - Create SqliteAdapter using bun:sqlite with auto-schema init - Add SqlDialect helpers for database-specific SQL generation - Update connection.ts with auto-detection (DATABASE_URL → Postgres, else SQLite) - Update isolation-environments.ts to use dialect helpers - CLI now works without DATABASE_URL (uses ~/.archon/archon.db) Part B: CLI Isolation Integration - Add --branch/-b flag to create/reuse worktrees for workflows - Add --no-worktree flag to run on branch directly without isolation - Add isolation list command to show all active worktrees - Add isolation cleanup command to remove stale environments - Auto-register codebase when using --branch from git repo New git utilities: - findRepoRoot: Find git repository root from any path - getRemoteUrl: Get origin remote URL - checkout: Checkout branch (creating if needed) * docs: Update documentation for Phase 3 - SQLite support and CLI isolation * fix: Address all PR review issues for database abstraction Critical fixes: - Use dialect helpers (now(), jsonMerge, jsonArrayContains) in all DB operations - Replace hardcoded PostgreSQL NOW(), ::jsonb, and JSON operators - Add rowCount validation to updateStatus() and updateMetadata() - Improve PostgreSQL pool error logging with structured context Important fixes: - Add explicit null check in getDialect() instead of non-null assertion - Add warning for unsupported UPDATE/DELETE RETURNING in SQLite - Throw error in extractTableName() on parse failure instead of empty string - Track codebaseLookupError to provide clearer errors when --branch fails - Couple IDatabase with SqlDialect via readonly sql property Code simplifications: - Extract loadWorkflows() helper to DRY duplicate error handling - Fix N+1 query in getCodebases() by including repository_url in JOIN - Cache sql.toUpperCase() to avoid redundant calls All changes verified with: - Type-check passes - All 1082 tests pass - CLI commands tested with both SQLite and PostgreSQL * docs: Add SQLite support to getting-started, configuration, and architecture guides * refactor: Simplify Phase 3 code for clarity and maintainability - sqlite.ts: Remove unused UPDATE branch from extractTableName, consolidate RETURNING clause handling into single condition - isolation.ts: Extract CodebaseInfo interface to reduce type duplication - workflow.ts: Extract actualBranchName variable for clearer intent - isolation-environments.ts: Rename variables for semantic clarity (staleActivityThreshold/staleCreationThreshold vs nowMinusDays1/2) * fix: Address all remaining PR review issues - SQLite: Throw error for UPDATE/DELETE RETURNING instead of warning - SQLite: Replace deprecated db.exec() with db.run() - Worktree: Throw for fatal errors (permission denied, not a git repo) - Types: Add import type for type-only imports in 4 db modules - Codebases: Add null check validation to createCodebase return - WorkflowRunOptions: Add JSDoc documenting constraint behavior - QueryResult: Add comment noting fields should be treated as readonly - Connection: Improve getDialect() error message with actionable details * fix: Complete type safety improvements for Phase 3 - QueryResult: Make rows and rowCount readonly to prevent mutation - WorkflowRunOptions: Use discriminated union to prevent invalid states (noWorktree can only be set when branchName is provided) - Update all database functions to return readonly arrays - Fix CLI call site to properly construct options object * fix: Add getDialect mock to database tests Tests were failing because they expected hardcoded PostgreSQL SQL (NOW(), metadata || $1::jsonb) but the code now uses dialect helpers. - Add mockPostgresDialect to test/mocks/database.ts - Update all db test files to mock getDialect() returning PostgreSQL dialect - Tests now properly verify the SQL generated by dialect helpers
4.7 KiB
4.7 KiB
Configuration Guide
Archon supports a layered configuration system with sensible defaults, optional YAML config files, and environment variable overrides.
Directory Structure
User-Level (~/.archon/)
~/.archon/
├── workspaces/ # Cloned repositories
│ └── owner/repo/
├── worktrees/ # Git worktrees for isolation
│ └── repo-name/
│ └── branch-name/
├── archon.db # SQLite database (when DATABASE_URL not set)
└── config.yaml # Global configuration (optional)
Repository-Level (.archon/)
.archon/
├── commands/ # Custom command templates
│ └── plan.md
├── workflows/ # Future: workflow definitions
└── config.yaml # Repo-specific configuration (optional)
Configuration Priority
Settings are loaded in this order (later overrides earlier):
- Defaults - Sensible built-in defaults
- Global Config -
~/.archon/config.yaml - Repo Config -
.archon/config.yamlin repository - Environment Variables - Always highest priority
Global Configuration
Create ~/.archon/config.yaml for user-wide preferences:
# Default AI assistant
defaultAssistant: claude # or 'codex'
# Streaming preferences per platform
streaming:
telegram: stream # 'stream' or 'batch'
discord: batch
slack: batch
github: batch
# Custom paths (usually not needed)
paths:
workspaces: ~/.archon/workspaces
worktrees: ~/.archon/worktrees
# Concurrency limits
concurrency:
maxConversations: 10
Repository Configuration
Create .archon/config.yaml in any repository for project-specific settings:
# AI assistant for this project (used as default provider for workflows)
assistant: claude
# Commands configuration
commands:
folder: .archon/commands
autoLoad: true
# Worktree settings
worktree:
baseBranch: main
copyFiles: # Optional: Additional files to copy to worktrees
- .env.example -> .env # Rename during copy
- .vscode # Copy entire directory
# Defaults configuration
defaults:
copyDefaults: false # Set to false to skip copying bundled commands/workflows on clone
Default behavior: The .archon/ directory is always copied to worktrees automatically (contains artifacts, plans, workflows). Use copyFiles only for additional files like .env or .vscode.
Defaults behavior: When you /clone a repository, bundled default commands and workflows are automatically copied to .archon/commands/ and .archon/workflows/ if those directories don't exist. Set defaults.copyDefaults: false to skip this.
Environment Variables
Environment variables override all other configuration:
| Variable | Description | Default |
|---|---|---|
DATABASE_URL |
PostgreSQL connection (optional) | SQLite at ~/.archon/archon.db if not set |
ARCHON_HOME |
Base directory for Archon | ~/.archon |
DEFAULT_AI_ASSISTANT |
Default AI assistant | claude |
TELEGRAM_STREAMING_MODE |
Telegram streaming | stream |
DISCORD_STREAMING_MODE |
Discord streaming | batch |
SLACK_STREAMING_MODE |
Slack streaming | batch |
GITHUB_STREAMING_MODE |
GitHub streaming | batch |
MAX_CONCURRENT_CONVERSATIONS |
Concurrency limit | 10 |
Docker Configuration
In Docker containers, paths are automatically set:
/.archon/
├── workspaces/
└── worktrees/
Environment variables still work and override defaults.
Command Folder Detection
When cloning or switching repositories, Archon looks for commands in this priority order:
.archon/commands/- Always searched first- Configured folder from
commands.folderin.archon/config.yaml(if specified)
Example .archon/config.yaml:
commands:
folder: .claude/commands/archon # Additional folder to search
autoLoad: true
Examples
Minimal Setup (Using Defaults)
No configuration needed! Archon works out of the box with:
~/.archon/for all managed files- Claude as default AI assistant
- Platform-appropriate streaming modes
Custom AI Preference
# ~/.archon/config.yaml
defaultAssistant: codex
Project-Specific Settings
# .archon/config.yaml in your repo
assistant: claude # Workflows inherit this provider unless they specify their own
commands:
autoLoad: true
Docker with Custom Volume
docker run -v /my/data:/.archon ghcr.io/dynamous-community/remote-coding-agent