orient/README.md

Orient Service

AI agent coordination for Egregore.

Purpose

Provides orientation and task management for AI agents (like Claude Code). Manages tickets, context topics, rules, and history. This service helps AI sessions understand what needs doing and track their work.

Endpoints

Endpoint	Method	Description
/orient	GET	Full orientation (status, tickets, rules, context)
/tickets	GET/POST	List or create tickets
/tickets/{id}	GET/PATCH	Get or update a ticket
/tickets/{id}/claim	POST	Claim a ticket to work on
/tickets/{id}/complete	POST	Mark ticket as completed
/tickets/{id}/notes	POST	Add progress note
/context/{topic}	GET	Load context for a topic
/rules	GET/PUT	Get or update rules
/history	GET/POST	View or log events
/health	GET	Health check

MCP Integration

This service is exposed as an MCP server for Claude Code integration. The MCP tools map directly to the HTTP endpoints above.

Configuration

Data is stored in ~/data/:

• tickets/ - Individual ticket JSON files
• context/ - Topic context files
• rules.json - Self-improving rules
• history.json - Event log
• status.json - System status

Running

# Build (Rust)
cd ~/services/orient
cargo build --release

# Run directly
./target/release/orient

# Or via systemd
sudo systemctl start orient
sudo systemctl status orient

Technology

Written in Rust using rouille for HTTP. Chosen for low memory footprint and fast startup.

Ticket System

Tickets have:

• Priority (1-10, lower = higher)
• Status (open/claimed/completed)
• Dependencies (must complete first)
• Acceptance criteria
• Progress notes