docs: reconcile hib_changes onto flat structure
Bring over comprehensive documentation, CLI tools, and project scaffolding from the archived v2/ branch onto the rebuilt flat main. All v2/ path references updated to match flat layout. - docs/: architecture, decisions, phases, progress, findings, etc. - docker/tempo: telemetry stack (Grafana + Tempo) - CLAUDE.md, .claude/CLAUDE.md: comprehensive project guides - CHANGELOG.md, TODO.md, README.md: project meta - consult, ctx: CLI tools - .gitignore: merged entries from both branches
This commit is contained in:
Hibryda
parent
37b2b82ae5
commit
356660f17d
29 changed files with 7673 additions and 66 deletions
160
README.md
160
README.md
|
|
@ -1,47 +1,141 @@
|
|||
# Svelte + TS + Vite
|
||||
# Agent Orchestrator
|
||||
|
||||
This template should help get you started developing with Svelte and TypeScript in Vite.
|
||||
Multi-project agent dashboard for orchestrating Claude AI teams across multiple codebases simultaneously. Built with Tauri 2.x (Rust) + Svelte 5 + Claude Agent SDK.
|
||||
|
||||
## Recommended IDE Setup
|
||||
|
||||
|
||||
[VS Code](https://code.visualstudio.com/) + [Svelte](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode).
|
||||
## What it does
|
||||
|
||||
## Need an official Svelte framework?
|
||||
Agent Orchestrator lets you run multiple Claude Code agents in parallel, organized into project groups. Each agent gets its own terminal, file browser, and Claude session. Agents communicate with each other via built-in messaging (btmsg) and coordinate work through a shared task board (bttask).
|
||||
|
||||
Check out [SvelteKit](https://github.com/sveltejs/kit#readme), which is also powered by Vite. Deploy anywhere with its serverless-first approach and adapt to various platforms, with out of the box support for TypeScript, SCSS, and Less, and easily-added support for mdsvex, GraphQL, PostCSS, Tailwind CSS, and more.
|
||||
## Key Features
|
||||
|
||||
## Technical considerations
|
||||
### Multi-Agent Orchestration
|
||||
- **Project groups** — up to 5 projects side-by-side, adaptive layout (5 @ultrawide, 3 @1920px)
|
||||
- **Tier 1 agents** — Manager, Architect, Tester, Reviewer with role-specific tabs and auto-generated system prompts
|
||||
- **Tier 2 agents** — per-project Claude sessions with custom context
|
||||
- **btmsg** — inter-agent messaging CLI + UI (Activity Feed, DMs, Channels)
|
||||
- **bttask** — Kanban task board with role-based visibility (Manager CRUD, others read-only)
|
||||
- **Auto-wake scheduler** — 3 strategies (persistent, on-demand, smart) with configurable wake signals
|
||||
|
||||
**Why use this over SvelteKit?**
|
||||
### Per-Project Workspace
|
||||
- **Claude sessions** with session continuity, anchors, and structured output
|
||||
- **Terminal tabs** — shell, SSH, agent preview per project
|
||||
- **File browser** — CodeMirror 6 editor (15 languages), PDF viewer, CSV table
|
||||
- **Docs viewer** — live Markdown with Shiki syntax highlighting
|
||||
- **Context tab** — LLM context window visualization (token meter, turn breakdown)
|
||||
- **Metrics panel** — live health, SVG sparkline history, session stats
|
||||
|
||||
- It brings its own routing solution which might not be preferable for some users.
|
||||
- It is first and foremost a framework that just happens to use Vite under the hood, not a Vite app.
|
||||
### Multi-Provider Support
|
||||
- **Claude** (primary) — via Agent SDK sidecar
|
||||
- **Codex** — OpenAI Codex SDK adapter
|
||||
- **Ollama** — local models via native fetch
|
||||
|
||||
This template contains as little as possible to get started with Vite + TypeScript + Svelte, while taking into account the developer experience with regards to HMR and intellisense. It demonstrates capabilities on par with the other `create-vite` templates and is a good starting point for beginners dipping their toes into a Vite + Svelte project.
|
||||
### Production Hardening
|
||||
- **Sidecar supervisor** — crash recovery with exponential backoff
|
||||
- **Landlock sandbox** — Linux kernel process isolation for sidecar
|
||||
- **FTS5 search** — full-text search with Spotlight-style overlay (Ctrl+F)
|
||||
- **Plugin system** — sandboxed runtime with permission gates
|
||||
- **Secrets management** — system keyring integration
|
||||
- **Notifications** — OS + in-app notification center
|
||||
- **Agent health monitoring** — heartbeats, dead letter queue, audit log
|
||||
- **Optimistic locking** — bttask concurrent access protection
|
||||
- **Error classification** — 6 error types with auto-retry logic
|
||||
- **TLS relay** — encrypted WebSocket for remote machines
|
||||
- **WAL checkpoint** — periodic SQLite maintenance (5min interval)
|
||||
|
||||
Should you later need the extended capabilities and extensibility provided by SvelteKit, the template has been structured similarly to SvelteKit so that it is easy to migrate.
|
||||
### Developer Experience
|
||||
- **17 themes** — Catppuccin (4), Editor (7), Deep Dark (6)
|
||||
- **Keyboard-first UX** — Command Palette (Ctrl+K), 18+ commands, vi-style navigation
|
||||
- **Claude profiles** — per-project account switching
|
||||
- **Skill discovery** — type `/` in agent prompt for autocomplete
|
||||
- **ctx integration** — SQLite context database for cross-session memory
|
||||
|
||||
**Why `global.d.ts` instead of `compilerOptions.types` inside `jsconfig.json` or `tsconfig.json`?**
|
||||
### Testing
|
||||
- **516 vitest** + **159 cargo** + **109 E2E** tests
|
||||
- **E2E engine** — WebDriverIO + tauri-driver, Phase A/B/C scenarios
|
||||
- **LLM judge** — dual-mode CLI/API for semantic assertion (claude-haiku)
|
||||
- **CI** — GitHub Actions with xvfb + LLM-judged test gating
|
||||
|
||||
Setting `compilerOptions.types` shuts out all other types not explicitly listed in the configuration. Using triple-slash references keeps the default TypeScript setting of accepting type information from the entire workspace, while also adding `svelte` and `vite/client` type information.
|
||||
## Architecture
|
||||
|
||||
**Why include `.vscode/extensions.json`?**
|
||||
|
||||
Other templates indirectly recommend extensions via the README, but this file allows VS Code to prompt the user to install the recommended extension upon opening the project.
|
||||
|
||||
**Why enable `allowJs` in the TS template?**
|
||||
|
||||
While `allowJs: false` would indeed prevent the use of `.js` files in the project, it does not prevent the use of JavaScript syntax in `.svelte` files. In addition, it would force `checkJs: false`, bringing the worst of both worlds: not being able to guarantee the entire codebase is TypeScript, and also having worse typechecking for the existing JavaScript. In addition, there are valid use cases in which a mixed codebase may be relevant.
|
||||
|
||||
**Why is HMR not preserving my local component state?**
|
||||
|
||||
HMR state preservation comes with a number of gotchas! It has been disabled by default in both `svelte-hmr` and `@sveltejs/vite-plugin-svelte` due to its often surprising behavior. You can read the details [here](https://github.com/rixo/svelte-hmr#svelte-hmr).
|
||||
|
||||
If you have state that's important to retain within a component, consider creating an external store which would not be replaced by HMR.
|
||||
|
||||
```ts
|
||||
// store.ts
|
||||
// An extremely simple external store
|
||||
import { writable } from 'svelte/store'
|
||||
export default writable(0)
|
||||
```
|
||||
Agent Orchestrator (Tauri 2.x)
|
||||
├── Rust backend (src-tauri/)
|
||||
│ ├── Commands: groups, sessions, btmsg, bttask, search, secrets, plugins, notifications
|
||||
│ ├── bterminal-core: PtyManager, SidecarManager, EventSink trait
|
||||
│ └── bterminal-relay: WebSocket server for remote machines (+ TLS)
|
||||
├── Svelte 5 frontend (src/)
|
||||
│ ├── Workspace: ProjectGrid, ProjectBox (per-project tabs), StatusBar
|
||||
│ ├── Stores: workspace, agents, health, conflicts, wake-scheduler, plugins
|
||||
│ ├── Adapters: claude-bridge, btmsg-bridge, bttask-bridge, groups-bridge
|
||||
│ └── Agent dispatcher: sidecar event routing, session persistence, auto-anchoring
|
||||
└── Node.js sidecar (sidecar/)
|
||||
├── claude-runner.mjs (Agent SDK)
|
||||
├── codex-runner.mjs (OpenAI Codex)
|
||||
└── ollama-runner.mjs (local models)
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
Requires Node.js 20+, Rust 1.77+, WebKit2GTK 4.1, GTK3.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/DexterFromLab/agent-orchestrator.git
|
||||
cd agent-orchestrator/v2
|
||||
npm install
|
||||
npm run build:sidecar
|
||||
npm run tauri:dev
|
||||
```
|
||||
|
||||
### Build for distribution
|
||||
|
||||
```bash
|
||||
npm run tauri:build
|
||||
# Output: .deb + AppImage in target/release/bundle/
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Config: `~/.config/bterminal/groups.json` — project groups, agents, prompts (human-editable JSON).
|
||||
|
||||
Database: `~/.local/share/bterminal/` — sessions.db (sessions, metrics, anchors), btmsg.db (messages, tasks, agents).
|
||||
|
||||
## Multi-Machine Support
|
||||
|
||||
```
|
||||
Agent Orchestrator --WebSocket/TLS--> bterminal-relay (Remote Machine)
|
||||
├── PtyManager (remote terminals)
|
||||
└── SidecarManager (remote agents)
|
||||
```
|
||||
|
||||
```bash
|
||||
cd v2 && cargo build --release -p bterminal-relay
|
||||
./target/release/bterminal-relay --port 9750 --token <secret> --tls-cert cert.pem --tls-key key.pem
|
||||
```
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `Ctrl+K` | Command Palette |
|
||||
| `Ctrl+M` | Messages (CommsTab) |
|
||||
| `Ctrl+B` | Toggle sidebar |
|
||||
| `Ctrl+,` | Settings |
|
||||
| `Ctrl+F` | Full-text search |
|
||||
| `Ctrl+1-5` | Focus project by index |
|
||||
| `Escape` | Close overlay/sidebar |
|
||||
|
||||
## Documentation
|
||||
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [docs/decisions.md](docs/decisions.md) | Architecture decisions log |
|
||||
| [docs/progress/](docs/progress/) | Session progress logs (v2, v3, archive) |
|
||||
| [docs/release-notes.md](docs/release-notes.md) | v3.0 release notes |
|
||||
| [docs/e2e-testing.md](docs/e2e-testing.md) | E2E testing facility documentation |
|
||||
| [docs/multi-machine.md](docs/multi-machine.md) | Multi-machine relay architecture |
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue