site-nine¶

The headquarters for AI agent orchestration

· 1

Created: 2026-02-03 · Version: v0.2.0

The headquarters for AI agent orchestration

Overview¶

site-nine is an orchestration framework for AI-assisted software development. Work naturally with specialized AI agents through conversation, while site-nine handles project coordination behind the scenes.

Currently optimized for OpenCode, with planned support for Cursor, Aider, and other AI coding tools via an adapter architecture.

site-nine provides:

• Agent Session Management - Track which AI agents are working on what, with specialized roles (Engineer, Tester, Architect, etc.)
• Task Management System - SQLite-based project management with priorities and dependencies
• Daemon Naming System - 145+ mythology-based names for agent instances
• Multi-Agent Workflows - Run multiple specialized agents in parallel OpenCode terminals
• Dashboard - Real-time project overview

How It Works¶

1. Initialize site-nine in your project: s9 init
2. Summon a persona directly: s9 summon operator (or any role)
3. Talk to your agents naturally - they handle tasks, write code, run tests, and coordinate with each other
4. Run multiple agents in parallel terminals for complex workflows

Requirements¶

• Python 3.12 or later
• OpenCode - AI coding assistant
• Modern terminal with Unicode support (for rich output)

Installation¶

pip install site-nine

Or with uv:

uv pip install site-nine

Initialize a Project¶

In your project directory, run:

s9 init

This launches an interactive wizard that asks:

• Project name (defaults to directory name)
• Project type (python, typescript, go, rust, other)
• Project description
• Features to enable (task management, session tracking, etc.)
• Agent roles to include

After initialization, check that the .opencode directory was created:

ls .opencode/

Next Steps¶

Start Working with Agents¶

The Director (you) can summon agents in two ways:

Option 1: Direct Summon (Recommended)¶

Use the s9 summon command to launch OpenCode with an agent automatically:

s9 summon operator

This will start OpenCode and immediately initialize an agent session with the specified role.

Option 2: Manual Summon via OpenCode¶

Launch OpenCode manually and use the /summon slash command:

opencode

Then execute the summon command to start an agent session:

/summon

This will guide you through selecting an agent role (Engineer, Tester, Architect, etc.) and choosing a daemon name from mythology. Once summoned, the Director can talk to the agent naturally through conversation.

Documentation¶

• Quickstart Guide - Get started in 5 minutes
• Agent Roles - Learn about specialized agent types
• Advanced Topics - Multi-agent workflows and patterns
• CLI Reference - Complete command documentation
• Full Documentation

Contributing / Development¶

Want to contribute to site-nine or develop it locally? Here's how to get started.

Development Setup¶

# Install site-nine in editable mode (REQUIRED for development)
uv sync

# Install as uv tool (recommended for CLI access)
uv tool install --editable .

# Verify installation
s9 --help

# Configure environment (optional - Docker works without .env)
cp .env.example .env
# Edit .env if you need custom configuration

# Start docker services and open web demo
make demo
# This starts Docker services and opens web demo at http://localhost:15000

# Stop when done
docker compose down

Running Tests¶

# Start Docker services for testing
docker compose up -d

# Run all tests
make qa/test-all

# Run unit tests only
make qa/test

# Run integration tests
make qa/test-integration

Development Commands¶

# Quality checks
make qa                      # Run all checks (test + lint + types)
make qa/format               # Format code
make qa/lint                 # Lint code

# Docker (advanced)
docker compose up -d         # Start services
docker compose down          # Stop services
docker compose logs -f       # View logs

# Help
make help                    # Show all available commands

Technology Stack¶

• Python 3.12+ with uv for package management
• FastMCP - Python framework
• SQLAlchemy - Database access (PostgreSQL, MySQL, SQLite)
• DuckDB - Knowledge base (embedded analytics)
• pytest/pytest-bdd - Testing
• ruff - Formatting and linting
• basedpyright - Type checking

Project Structure¶

site-nine/
├── src/
│   └── site_nine/           # Main package
│       ├── cli/             # CLI commands
│       ├── core/            # Core framework
│       └── templates/       # Project templates
├── tests/                   # Unit tests
├── .opencode/               # OpenCode agent configuration
│   ├── docs/                # Agent instructions
│   ├── work/                # Session logs and tasks
│   ├── data/                # SQLite database
│   └── scripts/             # Utility scripts
├── .env.example             # Configuration template
├── Makefile                 # Development tasks
└── pyproject.toml           # Project config

Agent Roles Overview¶

site-nine development uses 8 specialized agent roles for different types of work:

• Administrator - Primary interface and coordinator, delegates to specialized agents
• Architect - Design and planning specialist, creates technical designs
• Engineer - Implementation specialist, writes code and tests
• Tester - Quality assurance specialist, runs tests and validates features
• Documentarian - Documentation specialist, writes and maintains docs
• Designer - User experience specialist, designs CLI output and workflows
• Inspector - Code review specialist, reviews code and finds issues
• Operator - Meta-development specialist, maintains .opencode/ infrastructure

For detailed role documentation, see Agent Roles

License¶

MIT License - See LICENSE.md for details