agents-orchestrator/agent-orchestrator
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: restructure documentation into multilevel directory layout

Browse source 
New structure: docs/ split into 11 subdirectories (getting-started/,
agents/, providers/, sidecar/, multi-machine/, plugins/, config/,
production/, architecture/, contributing/, pro/).

New files:
- docs/README.md: navigation index with audience table
- docs/getting-started/quickstart.md: install, build, first session
- docs/config/ref-settings.md: all env vars, config files, databases
- docs/architecture/overview.md: split from architecture.md (>300 lines)
- docs/pro/README.md: Pro edition overview
- docs/pro/features/analytics.md: analytics dashboard docs
- docs/pro/features/cost-intelligence.md: budget + router docs

Remaining docs being written by background agents — will be committed
in follow-up when complete.
This commit is contained in:
Hibryda 2026-03-17 04:15:15 +01:00
parent 738574b9f0
commit 8251321dac
7 changed files with 1268 additions and 59 deletions
Download patch file Download diff file Expand all files Collapse all files

139
docs/README.md
View file

@ -1,79 +1,87 @@
---
title: "Documentation"
role: part
parent: null
order: 1
description: "Project documentation index"
---
# Agents Orchestrator — Documentation
# Agent Orchestrator Documentation
Multi-project AI agent dashboard with terminal, SSH, and multi-provider session management.
Built with Tauri 2.x (Rust) + Svelte 5 + Claude Agent SDK.
Agent Orchestrator (formerly Agents Orchestrator) is a multi-project AI agent orchestration dashboard built with Tauri 2.x, Svelte 5, and the Claude Agent SDK. It transforms a traditional terminal emulator into a mission control for running, monitoring, and coordinating multiple AI agent sessions across multiple codebases simultaneously.
> **Source of truth.** Before making changes, consult these docs. After making changes, update them.
The application has three major version milestones:
## Quick Navigation
- **v1** — A single-file Python GTK3+VTE terminal emulator with Claude Code session management. Production-stable, still shipped as `agor`.
- **v2** — A ground-up rewrite using Tauri 2.x (Rust backend) + Svelte 5 (frontend). Multi-pane terminal with structured agent sessions, subagent tree visualization, session persistence, multi-machine relay support, 17 themes, and comprehensive packaging.
- **v3 (Mission Control)** — A further redesign on top of v2's codebase. Replaces the free-form pane grid with a project-group dashboard. Adds multi-agent orchestration (4 management roles), inter-agent messaging (btmsg), task boards (bttask), session anchors, health monitoring, FTS5 search, plugin system, Landlock sandboxing, secrets management, and 704 automated tests.
> **Important:** The `docs/` directory is the single source of truth for this project. Before making changes, consult the docs. After making changes, update the docs.
---
| Audience | Start Here |
|----------|-----------|
| New users | [Getting Started](getting-started/quickstart.md) |
| Contributors | [Dual-Repo Workflow](contributing/dual-repo-workflow.md), [Testing](contributing/testing.md) |
| Pro customers | [Pro Edition](pro/README.md), [Marketplace](pro/marketplace/README.md) |
| Plugin developers | [Plugin Development Guide](plugins/guide-developing.md) |
## Documentation Map
### Architecture & Design
### Getting Started
| Document | What It Covers |
|----------|---------------|
| [architecture.md](architecture.md) | End-to-end system architecture: Rust backend, Svelte frontend, sidecar layer, data model, layout system, data flow, IPC patterns |
| [decisions.md](decisions.md) | Architecture decisions log: rationale and dates for all major design choices |
| [multi-machine.md](multi-machine.md) | Multi-machine relay architecture: agor-core extraction, agor-relay binary, RemoteManager, WebSocket protocol, reconnection |
- [Quickstart](getting-started/quickstart.md) — install, build, first agent session
### Subsystem Guides
### Architecture
| Document | What It Covers |
|----------|---------------|
| [sidecar.md](sidecar.md) | Sidecar process lifecycle, multi-provider runners (Claude/Codex/Ollama), env var stripping, CLI detection, NDJSON protocol |
| [orchestration.md](orchestration.md) | Multi-agent orchestration: btmsg messaging, bttask kanban, Tier 1/2 agent roles, wake scheduler, system prompts |
| [production.md](production.md) | Production hardening: sidecar supervisor, Landlock sandbox, FTS5 search, plugin system, secrets management, notifications, health monitoring, audit logging |
| [provider-adapter/](provider-adapter/) | Multi-provider adapter pattern: architecture decisions, coupling analysis, implementation progress |
- [System Overview](architecture/overview.md) — components, data flow, IPC patterns
- [Data Model](architecture/data-model.md) — SQLite schemas, layout, keyboard shortcuts
- [Decisions](architecture/decisions.md) — architecture decision log with rationale
- [Phases](architecture/phases.md) — v2 implementation phases (P1-7 + multi-machine A-D)
- [Research Findings](architecture/findings.md) — SDK, performance, coupling analysis
### Implementation & Progress
### Agents & Orchestration
| Document | What It Covers |
|----------|---------------|
| [phases.md](phases.md) | v2 implementation phases (1-7 + multi-machine A-D + profiles/skills) with checklists |
| [progress/v3.md](progress/v3.md) | v3 session-by-session progress log (Phases 1-10 + production hardening) |
| [progress/v2.md](progress/v2.md) | v2 session-by-session progress log (recent sessions) |
| [progress/v2-archive.md](progress/v2-archive.md) | Archived v2 progress (2026-03-05 to 2026-03-06 early) |
- [Orchestration](agents/orchestration.md) — btmsg, bttask, 4 management roles, wake scheduler, session anchors
- [btmsg Reference](agents/ref-btmsg.md) — inter-agent messaging CLI and database schema
- [bttask Reference](agents/ref-bttask.md) — kanban task board CLI and operations
### Research & Analysis
### Providers
| Document | What It Covers |
|----------|---------------|
| [findings.md](findings.md) | All research: Claude Agent SDK, Tauri+xterm.js, terminal performance, adversarial review, provider coupling, codebase reuse, session anchors, multi-agent design, theme evolution, performance measurements |
- [Provider Reference](providers/ref-providers.md) — Claude, Codex, Ollama, Aider: models, capabilities, routing
### Release & Testing
### Sidecar
| Document | What It Covers |
|----------|---------------|
| [release-notes.md](release-notes.md) | v3.0 release notes: feature summary, breaking changes, test coverage, known limitations |
| [e2e-testing.md](e2e-testing.md) | E2E testing facility: WebDriverIO fixtures, test mode, LLM judge, CI integration, troubleshooting |
- [Sidecar Architecture](sidecar/architecture.md) — runners, NDJSON protocol, crash recovery, env stripping
---
### Multi-Machine
## Quick Orientation
- [Relay Architecture](multi-machine/relay.md) — WebSocket server, TLS, SPKI pinning, reconnection
If you are new to this codebase, read the documents in this order:
### Production Hardening
1. **[architecture.md](architecture.md)** — Understand how the pieces fit together
2. **[decisions.md](decisions.md)** — Understand why things are built the way they are
3. **[sidecar.md](sidecar.md)** — Understand how agent sessions actually run
4. **[orchestration.md](orchestration.md)** — Understand multi-agent coordination
5. **[e2e-testing.md](e2e-testing.md)** — Understand how to test changes
- [Hardening](production/hardening.md) — sidecar supervisor, Landlock sandbox, WAL checkpoint, TLS relay
- [Features](production/features.md) — FTS5 search, plugin sandbox, secrets, notifications, audit, error classification
For research context, read [findings.md](findings.md). For implementation history, see [phases.md](phases.md) and [progress/](progress/).
### Configuration
- [Settings Reference](config/ref-settings.md) — env vars, config files, databases, themes, per-project settings
### Plugins
- [Plugin Development Guide](plugins/guide-developing.md) — Web Worker sandbox API, manifest, publishing, examples
### Contributing
- [Dual-Repo Workflow](contributing/dual-repo-workflow.md) — community vs commercial repos, sync, leak prevention
- [Testing](contributing/testing.md) — E2E fixtures, test mode, LLM judge, CI integration
### Pro Edition (Commercial)
- [Pro Overview](pro/README.md) — feature list, plugin architecture, IPC pattern
- [Analytics Dashboard](pro/features/analytics.md) — cost/token/model tracking over time
- [Cost Intelligence](pro/features/cost-intelligence.md) — budget governor, smart model router
- [Knowledge Base](pro/features/knowledge-base.md) — persistent memory, codebase symbol graph
- [Git Integration](pro/features/git-integration.md) — context injection, branch policy
- [Marketplace](pro/marketplace/README.md) — 13 plugins (8 free + 5 paid), catalog, install/update
### Release History
- [Release Notes](release-notes.md) — v3.0 features, breaking changes, requirements
### Progress Logs
- [v3 Progress](progress/v3.md) — session-by-session development log
- [v2 Progress](progress/v2.md)
- [v2 Archive](progress/v2-archive.md)
---
@ -82,10 +90,23 @@ For research context, read [findings.md](findings.md). For implementation histor
| Path | Purpose |
|------|---------|
| `src-tauri/src/` | Rust backend: commands, SQLite, btmsg, bttask, search, secrets, plugins |
| `agor-core/` | Shared Rust crate: PtyManager, SidecarManager, EventSink trait, Landlock sandbox |
| `agor-core/` | Shared Rust crate: PtyManager, SidecarManager, EventSink, Landlock sandbox |
| `agor-relay/` | Standalone relay binary for remote machine support |
| `agor-pro/` | Commercial plugin crate (Pro edition features) |
| `src/lib/` | Svelte 5 frontend: components, stores, adapters, utils, providers |
| `sidecar/` | Agent sidecar runners (Claude, Codex, Ollama) — compiled to ESM bundles |
| `src/lib/commercial/` | Pro edition Svelte components and IPC bridge |
| `sidecar/` | Agent sidecar runners (Claude, Codex, Ollama, Aider) — ESM bundles |
| `tests/e2e/` | WebDriverIO E2E tests, fixtures, LLM judge |
| `ctx/` | Context manager CLI tool (SQLite-based, standalone) |
| `consult/` | Multi-model tribunal CLI (OpenRouter, standalone Python) |
| `tests/commercial/` | Pro edition tests (excluded from community builds) |
| `scripts/` | Build scripts, plugin scaffolding, test runner |
| `.githooks/` | Pre-push leak prevention hook |
## Reading Order for New Contributors
1. [Getting Started](getting-started/quickstart.md) — build and run
2. [System Overview](architecture/overview.md) — how the pieces fit
3. [Decisions](architecture/decisions.md) — why things are built this way
4. [Sidecar Architecture](sidecar/architecture.md) — how agent sessions run
5. [Orchestration](agents/orchestration.md) — multi-agent coordination
6. [Testing](contributing/testing.md) — how to test changes
7. [Dual-Repo Workflow](contributing/dual-repo-workflow.md) — how to contribute