π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
Checkpoint: File edits
rUvbc4038e900b4
diff --git a/v3/implementation/adrs/ADR-052-statusline-observability-system.md b/v3/implementation/adrs/ADR-052-statusline-observability-system.mdnew file mode 100644index 0000000000..a531b3f7dd--- /dev/null+++ b/v3/implementation/adrs/ADR-052-statusline-observability-system.md@@ -0,0 +1,394 @@+# ADR-052: Statusline Observability System++**Status:** Implemented+**Date:** 2026-02-10+**Authors:** RuvNet, Claude Flow Team+**Version:** 1.0.0+**Related:** ADR-051 (Infinite Context), ADR-048 (Auto Memory Integration), ADR-006 (Unified Memory), ADR-026 (3-Tier Model Routing)++## Context++### The Problem: Invisible System State++Claude Code operates with multiple concurrent subsystems β swarm agents, memory+backends, neural learning, security scanning, context management β but provides no+unified visibility into their state. Developers working in long sessions need to know:++- How much context window remains before compaction triggers+- Whether the swarm has active agents or is idle+- If the intelligence system is learning from patterns+- What security posture the project maintains+- Whether archived memory is being utilized++Without real-time feedback, developers make blind decisions about when to start new+sessions, whether agents are drifting, and if the system is operating optimally.++### What Claude Code Provides++Claude Code supports a `statusLine` configuration in `.claude/settings.json`:++```json+{+ "statusLine": {+ "type": "command",+ "command": "<shell command>",+ "refreshMs": 5000,+ "enabled": true+ }+}+```++The command receives JSON on stdin with workspace metadata, model info, and optional+context window data. Its stdout is displayed as a persistent status bar in the Claude+Code terminal UI.++### What We Built++A multi-tier statusline system with 4 implementations, a TypeScript generator for+`npx claude-flow init`, and real-time data feeds from 8+ subsystems.++## Decision++Implement a layered statusline architecture:++1. **Active statusline** (`.claude/statusline.sh`) β Bash script for the current+ project, read from `settings.json` `statusLine.command`+2. **Generated statusline** (`.claude/helpers/statusline.cjs`) β CommonJS script+ created by `npx claude-flow init`, comprehensive with 12+ metric panels+3. **Lightweight statusline** (`.claude/statusline.mjs`) β ES module for agentic-flow+ integration, compact pipe-separated format+4. **Command statusline** (`.claude/statusline-command.sh`) β JSON-input focused,+ shows swarm topology and task metrics+5. **Generator** (`v3/@claude-flow/cli/src/init/statusline-generator.ts`) β TypeScript+ that produces the `.cjs` script during project initialization++## Architecture++### System Context++```+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+β Claude Code Terminal β+β β+β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β+β β statusLine.command executes every refreshMs (5000ms) β β+β β β β+β β stdin: { workspace, model, context_window } β β+β β stdout: ANSI-colored multi-line status display β β+β ββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββ β+β β β+β βΌ β+β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β+β β .claude/statusline.sh (active) β β+β β β β+β β Reads 8 data sources: β β+β β β β+β β βββββββββββββββββββ ββββββββββββββββββββββββ β β+β β β autopilot-state β β v3-progress.json β β β+β β β .json β β (DDD domains) β β β+β β β Context: 27% β β Domains: 5/5 β β β+β β βββββββββββββββββββ ββββββββββββββββββββββββ β β+β β β β+β β βββββββββββββββββββ ββββββββββββββββββββββββ β β+β β β learning.json β β audit-status.json β β β+β β β Intel: 86% β β CVE: 3/3 CLEAN β β β+β β βββββββββββββββββββ ββββββββββββββββββββββββ β β+β β β β+β β βββββββββββββββββββ ββββββββββββββββββββββββ β β+β β β patterns.db β β transcript-archive β β β+β β β (SQLite) β β .db (SQLite) β β β+β β β Quality: 0.999 β β Entries: 35 β β β+β β βββββββββββββββββββ ββββββββββββββββββββββββ β β+β β β β+β β βββββββββββββββββββ ββββββββββββββββββββββββ β β+β β β swarm-activity β β ps aux (process) β β β+β β β .json β β Node/MCP detection β β β+β β β Agents: 3/15 β β Memory: 2782MB β β β+β β βββββββββββββββββββ ββββββββββββββββββββββββ β β+β β β β+β β Output (4 lines + separators): β β+β β β Claude Flow V3 β user β β branch β Model β β+β β βββββββββββββββββββββββββββββββββββββββββ β β+β β ποΈ DDD Domains [βββββ] 5/5 β‘ 1.0x β 2.49x-7.47x β β+β β π€ Swarm β [3/15] π₯ 0 π’ CVE 3/3 πΎ 2782MB β β+β β π‘οΈ 27% 54.7K β π§ 86% β β+β β π§ Architecture DDD β79% β Security βCLEAN β β+β β Memory βAgentDB β Integration β β β+β β βββββββββββββββββββββββββββββββββββββββββ β β+β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+```++### Data Sources++| Source File | Subsystem | Metrics | Updated By |+|-------------|-----------|---------|------------|+| `.claude-flow/data/autopilot-state.json` | Context Autopilot (ADR-051) | Token %, token count, prune cycles, growth trend | `context-persistence-hook.mjs` on every `UserPromptSubmit` |+| `.claude-flow/metrics/v3-progress.json` | DDD Architecture | Domain count, DDD progress %, active agents | `init` command, manual updates |+| `.claude-flow/security/audit-status.json` | Security | CVE count, audit status (CLEAN/PENDING) | `security scan` command |+| `.claude-flow/metrics/performance.json` | Performance | Flash Attention speedup | `performance benchmark` command |+| `.claude-flow/metrics/learning.json` | Intelligence | Score (0-100), routing accuracy, SONA status | `hooks post-task`, neural training |+| `.claude-flow/learning/patterns.db` | Pattern DB (SQLite) | Short/long-term pattern counts, avg quality | `hooks intelligence`, neural training |+| `.claude-flow/data/transcript-archive.db` | Context Archive (SQLite) | Entry count, session count | `context-persistence-hook.mjs` |+| `.claude-flow/metrics/swarm-activity.json` | Swarm Monitor | Active agent count, swarm state | Swarm monitor daemon |+| `ps aux` (process table) | System | Node/MCP memory, active processes | Real-time OS query |+| `git` (VCS) | Repository | Branch name, status | Real-time git query |+| `gh api` (GitHub) | GitHub | Username | Cached API call |++### Statusline Implementations++#### 1. Active Statusline β `.claude/statusline.sh` (432 lines)++The currently wired script in `settings.json`. Bash-based for maximum compatibility.++**Display Layout:**++```+Line 0: β Claude Flow V3 β user β β branch β Model+Line -: βββββββββββββββββββββββββββββββββββββββββ+Line 1: ποΈ DDD Domains [βββββ] 5/5 β‘ speedup β target+Line 2: π€ Swarm β [N/15] π₯ sub π’ CVE X/3 πΎ MEM π‘οΈ CTX% π§ INT%+Line 3: π§ Architecture DDD βN% β Security βSTATUS β Memory βAgentDB β Integration β+Line -: βββββββββββββββββββββββββββββββββββββββββ+```++**Metric Icons:**++| Icon | Metric | Source |+|------|--------|--------|+| `ποΈ` | DDD domain progress | v3-progress.json |+| `β‘` | Flash Attention speedup | performance.json |+| `π€` | Swarm agent count | swarm-activity.json + ps |+| `β/β` | Active/inactive processes | ps aux |+| `π₯` | Sub-agent count | ps aux (Task tool agents) |+| `π¨` | Message queue depth | swarm-comms.sh |+| `π’/π‘/π΄` | Security CVE status | audit-status.json |+| `πΎ` | Node process memory | ps aux RSS |+| `π‘οΈ/π` | Context % (autopilot/legacy) | autopilot-state.json |+| `β/β³N` | Compaction blocked / prune cycles | autopilot-state.json |+| `π§ ` | Intelligence score | learning.json + patterns.db |+| `π§` | Architecture status | v3-progress.json |++**Color Thresholds:**++| Metric | Green | Cyan | Yellow | Red |+|--------|-------|------|--------|-----|+| Context % | 0-49 | 50-69 | 70-84 | 85+ |+| Intelligence % | 75+ | 50-74 | 25-49 | 0-24 |+| Agents | 8+ | β | 1-7 | 0 |+| Domains | 5 | β | 1-4 | 0 |++**Context Autopilot Integration (ADR-051):**++The statusline reads from `autopilot-state.json` which is written by the+`context-persistence-hook.mjs` on every `UserPromptSubmit` hook:++```json+{+ "sessionId": "f1bd5b59-...",+ "lastTokenEstimate": 54700,+ "lastPercentage": 0.274,+ "pruneCount": 0,+ "warningIssued": false,+ "history": [{ "ts": ..., "tokens": ..., "pct": ..., "turns": ... }]+}+```++When autopilot is active:+- Icon changes from `π` (folder) to `π‘οΈ` (shield)+- Token count shown (e.g., `54.7K`)+- Prune indicator: `β` (no prunes needed) or `β³N` (N prune cycles)++**Intelligence Score Computation:**++```+Base: learning.json β intelligence.score (0-100)++ Boost: patterns.db β AVG(quality) Γ 20 (up to +20)++ Boost: transcript-archive.db β COUNT(*) / 10 (up to +10)+= Final: capped at 100+```++#### 2. Generated Statusline β `.claude/helpers/statusline.cjs` (1,193 lines)++Created by `npx claude-flow init`. CommonJS for ES module project compatibility.++**12 Metric Panels:**++| Panel | Function | Lines |+|-------|----------|-------|+| User Info | `getUserInfo()` | Git user, branch, model |+| Learning Stats | `getLearningStats()` | Intelligence loop data |+| V3 Progress | `getV3Progress()` | DDD from real metrics |+| Security | `getSecurityStatus()` | CVE tracking |+| Swarm | `getSwarmStatus()` | Cross-platform agent detection |+| System Metrics | `getSystemMetrics()` | Memory, intelligence, context |+| ADR Status | `getADRStatus()` | Architecture decision compliance |+| Hooks | `getHooksStatus()` | Hook enablement tracking |+| AgentDB | `getAgentDBStats()` | Vector count, HNSW index |+| Tests | `getTestStats()` | Test file/case counting |+| Integration | `getIntegrationStatus()` | MCP, database, API |+| Git | `getGitStatus()` | Modified, staged, untracked |++**Output Modes:**+- Default: Full ANSI-colored 4-line display+- `--json`: Pretty-printed JSON of all metrics+- `--compact`: Minified JSON++#### 3. Lightweight Statusline β `.claude/statusline.mjs` (110 lines)++ES module for agentic-flow integration. Compact pipe-separated format with 5-second+cache TTL for swarm status.++#### 4. Command Statusline β `.claude/statusline-command.sh` (177 lines)++JSON-input focused. Shows swarm topology configuration, CPU/memory (with color-coded+thresholds), session duration, task success rate with streak tracking, and hooks+activity status.++### Init System Integration++#### Generator β `v3/@claude-flow/cli/src/init/statusline-generator.ts` (1,317 lines)++Produces the `.cjs` script during `npx claude-flow init`:++```typescript+function generateStatuslineScript(options: InitOptions): string {+ // Generates 1,193-line CommonJS script with all metric panels+ // Configurable via StatuslineConfig interface+}++function generateStatuslineHook(options: InitOptions): string {+ // Generates shell integration hook for bash/zsh/starship+}+```++#### Settings Generator β `v3/@claude-flow/cli/src/init/settings-generator.ts`++Wires the statusline into `.claude/settings.json`:++```typescript+function generateStatusLineConfig(options: InitOptions): object {+ return {+ type: 'command',+ command: 'node .claude/helpers/statusline.cjs',+ refreshMs: config.refreshInterval, // Default: 5000+ enabled: config.enabled,+ };+}+```++#### Executor β `v3/@claude-flow/cli/src/init/executor.ts`++During init:+1. Copies advanced statusline files (`.sh`, `.mjs`) from package source if available+2. Falls back to generating `.cjs` + hook via `statusline-generator.ts`+3. On upgrade: force-updates statusline while preserving metrics++#### Types β `v3/@claude-flow/cli/src/init/types.ts`++```typescript+interface StatuslineConfig {+ enabled: boolean; // Enable statusline+ showProgress: boolean; // V3 DDD progress+ showSecurity: boolean; // CVE status+ showSwarm: boolean; // Swarm agent count+ showHooks: boolean; // Hooks metrics+ showPerformance: boolean; // Performance targets+ refreshInterval: number; // Refresh ms (default: 5000)+}+```++### Init Presets++| Preset | Statusline |+|--------|------------|+| `full` | All panels enabled, 5s refresh |+| `minimal` | Disabled (only core functionality) |+| `security` | Security + swarm panels |+| `development` | All panels enabled |++## File Inventory++| File | Lines | Language | Role |+|------|-------|----------|------|+| `.claude/statusline.sh` | 432 | Bash | Active statusline (settings.json) |+| `.claude/helpers/statusline.cjs` | 1,193 | CommonJS | Generated comprehensive statusline |+| `.claude/statusline.mjs` | 110 | ES Module | Lightweight agentic-flow statusline |+| `.claude/statusline-command.sh` | 177 | Bash | JSON-input command statusline |+| `v3/@claude-flow/cli/src/init/statusline-generator.ts` | 1,317 | TypeScript | Generator for `.cjs` during init |+| `v3/@claude-flow/cli/src/init/settings-generator.ts` | ~20 | TypeScript | Wires statusLine into settings.json |+| `v3/@claude-flow/cli/src/init/executor.ts` | ~60 | TypeScript | Copy/generate during init |+| `v3/@claude-flow/cli/src/init/types.ts` | ~20 | TypeScript | `StatuslineConfig` interface |++## Performance++| Operation | Budget | Actual |+|-----------|--------|--------|+| statusline.sh full execution | 1000ms | ~200ms |+| JSON file reads (jq) | 50ms each | ~10ms each |+| SQLite queries (sqlite3) | 100ms each | ~5ms each |+| Process detection (ps aux) | 200ms | ~50ms |+| Git operations | 100ms | ~20ms |+| GitHub API (gh, cached) | 500ms | ~100ms (first), ~0ms (cached) |+| **Total refresh** | **5000ms** | **~400ms** |++## Security Considerations++1. **No secrets exposed**: Statusline only reads metric files, never credentials+2. **Read-only**: All data sources are read-only file access or process inspection+3. **No network**: statusline.sh makes no network calls (gh API is cached from init)+4. **Graceful failure**: Every metric read is wrapped in error suppression (`2>/dev/null`)+5. **No code execution**: Statusline never evaluates dynamic code from data files++## Consequences++### Positive++1. **Real-time visibility**: Developers see context %, intelligence, swarm, and security+ at a glance without switching windows or running commands+2. **Context Autopilot feedback**: The `π‘οΈ 27% 54.7K β` display confirms compaction+ is blocked and shows exact token usage β no surprises+3. **Intelligence tracking**: The `π§ 86%` score motivates pattern storage and shows+ the system is learning from session interactions+4. **Multi-implementation flexibility**: Bash for current use, CJS for init portability,+ MJS for agentic-flow, each optimized for its context+5. **Zero-dependency active script**: statusline.sh uses only bash builtins, jq, and+ sqlite3 β no npm install required++### Negative++1. **4 implementations**: Maintenance burden of 4 separate statusline files. Mitigation:+ the generator produces the CJS version programmatically; the bash scripts are stable+2. **Process detection heuristics**: `ps aux | grep` is fragile for counting agents.+ Mitigation: swarm-activity.json from the monitor daemon is preferred when available+3. **SQLite dependency**: Intelligence score reads from `patterns.db` and+ `transcript-archive.db` via `sqlite3` CLI. Mitigation: falls back to `learning.json`+ if sqlite3 is not installed++### Neutral++1. **5-second refresh**: Default `refreshMs: 5000` balances freshness with CPU cost+2. **ANSI colors**: Terminal-dependent rendering. Claude Code's terminal handles ANSI+ well; raw SSH sessions may vary+3. **JSON data coupling**: Statusline depends on specific JSON key paths in metric+ files. Changes to metric formats require statusline updates++## Future Enhancements++1. **Unified statusline**: Consolidate 4 implementations into a single TypeScript+ module that compiles to CJS, with bash as a thin wrapper+2. **WebSocket feed**: Replace file polling with event-driven updates from the MCP+ server for sub-second refresh+3. **Customizable layout**: Allow users to configure which panels appear and in what+ order via `StatuslineConfig`+4. **Sparkline graphs**: Show context growth trend as a sparkline character sequence+ (e.g., `ββββ β` for rising usage)+5. **Team statusline**: When Agent Teams are active, show teammate status inline++## References++- Claude Code `statusLine` config: `@anthropic-ai/claude-agent-sdk` settings schema+- ADR-051: Infinite Context via Compaction-to-Memory Bridge (autopilot-state.json)+- ADR-048: Auto Memory Integration (learning patterns)+- ADR-006: Unified Memory Service (AgentDB)+- ADR-026: 3-Tier Model Routing (intelligence scoring)