mirror of https://github.com/coleam00/Archon synced 2026-04-21 13:37:41 +00:00

Add Archon distribution config and directory structure (#101 )

* Add Archon distribution config and directory structure

- Create centralized path resolution in src/utils/archon-paths.ts
- Add YAML configuration system (src/config/) with layered loading
- Update Dockerfile and docker-compose for /.archon/ directory
- Add GHCR publish workflow for multi-arch Docker builds
- Create deploy/ directory with end-user docker-compose
- Add /init command to create .archon structure in repos
- Add docs/configuration.md reference guide
- Update README with Quick Start section
- Add bun run validate script
- Update tests for new path defaults (~/.archon/)

Directory structure:
- Local: ~/.archon/{workspaces,worktrees,config.yaml}
- Docker: /.archon/{workspaces,worktrees}
- Repo: .archon/{commands,workflows,config.yaml}

Legacy WORKSPACE_PATH and WORKTREE_BASE env vars still supported.

* Complete Archon distribution config implementation

- Wire up config system in src/index.ts (Task 3.5)
- Remove legacy WORKSPACE_PATH and WORKTREE_BASE support
- Add logConfig() function to config-loader.ts
- Update docker-compose.yml to use ARCHON_DOCKER env var
- Remove legacy env vars from .env.example
- Update all documentation to reference ARCHON_HOME
- Create scripts/validate-setup.sh for setup validation
- Add setup:check script to package.json
- Create docs/getting-started.md guide
- Create docs/archon-architecture.md technical docs
- Update tests to use ARCHON_HOME instead of legacy vars
- Fix validate.md command template for new paths

All plan phases now complete:
- Phase 1: Archon Directory Structure
- Phase 2: Docker Distribution
- Phase 3: YAML Configuration System
- Phase 4: Developer Experience
- Phase 5: Documentation

2025-12-17 21:45:41 +02:00

3.6 KiB

Raw Blame History

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/
└── 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.yaml in 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
assistant: claude

# Commands configuration
commands:
  folder: .archon/commands
  autoLoad: true

# Worktree settings
worktree:
  baseBranch: main

Environment Variables

Environment variables override all other configuration:

Variable	Description	Default
`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/ - Archon-specific commands
.claude/commands/ - Claude Code standard location
.agents/commands/ - Alternative location

First found folder is used.

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
commands:
  autoLoad: true

Docker with Custom Volume

docker run -v /my/data:/.archon ghcr.io/dynamous-community/remote-coding-agent

3.6 KiB Raw Blame History