
chronos-agent
io.github.ptai-eng/chronos-agent
5D living code graph, AST symbol editing, refactoring & blast-radius gate in 1 Rust binary
Documentation
CHRONOS-AGENT
Single-binary Rust MCP server (Tree-sitter + KuzuDB + Sandboxed Rhai) for fresh-parse AST symbol editing, edge-verified multi-file refactoring, and blast-radius gating. No LSP daemon required.
30-Second Quickstart
Zero-install via npx (requires Node.js 18+; auto-fetches your OS release binary):
npx -y @ptai-eng/chronos-mcp --workspace .
Or install prebuilt binaries (chronos CLI + chronos-mcp server) without Node.js, C++, or Rust:
Windows (PowerShell):
irm https://raw.githubusercontent.com/ptai-eng/chronos-agent/main/scripts/install.ps1 | iex
macOS (Apple Silicon) & Linux (x64):
curl -fsSL https://raw.githubusercontent.com/ptai-eng/chronos-agent/main/scripts/install.sh | sh
(Other options: cargo-binstall via cargo binstall --git https://github.com/ptai-eng/chronos-agent chronos-cli chronos-mcp, packaging/homebrew/chronos.rb, or OCI container docker run -i --rm -v "${PWD}:/workspace" ghcr.io/ptai-eng/chronos-agent:1.8.1 via the Official MCP Registry.)
Bootstrap configs for Codex, Antigravity, Claude Code, Cursor, OpenCode, Windsurf, Copilot, and Cline in any workspace:
cd your-project
chronos init --client all --with-hooks
Or drop @ptai-eng/chronos-mcp (or chronos-mcp) directly into any MCP client config:
{
"mcpServers": {
"chronos-agent": {
"command": "npx",
"args": ["-y", "@ptai-eng/chronos-mcp", "--workspace", "."]
}
}
}
Table of Contents
- Why CHRONOS vs. Serena & Built-in Grep
- What's New in v1.8.1 & v1.8.0
- Core Architecture
- Capability Matrix
- 14 Canonical MCP Tools
- VS Code Extension
- CLI Command Suite & Build from Source
- Security & Local-First Guarantees
Why CHRONOS vs. Serena & Built-in Grep
Coding agents normally inspect repositories with sequential grep + line-range reads and apply raw string diffs without knowing who calls a function or whether foo also appears as an unrelated local variable.
| Aspect | Built-in Agent Grep / Line Edits | Daemon LSP MCPs (e.g. Serena) | CHRONOS-AGENT v1.8 |
|---|---|---|---|
| Runtime Model | Text regex per turn | Background language server daemon per language | Single Rust binary (<15ms queries, zero daemon) |
| Symbol Editing Safety | Trusts stale line numbers / diff hunks | LSP offsets + text rewrite | Fresh Tree-sitter re-parse on every write + 2-Stage Gate (syntax_error & blocked_requires_force when signature changes on callers) |
| Multi-File Rename | Global text search/replace risks corrupting locals & comments | Compiler/LSP reference list | AST identifier classification separating verified_edits (CALLS/TESTS/imports) from candidate_sites (obj.method(), shadowed locals) + atomic rollback |
| Impact & Test Awareness | None | Caller references when server is warm | KuzuDB graph + Git co-change coupling + Reverse-BFS entrypoints (verification_surfaces) + Mutation testing |
Hybrid Disambiguation (v1.8.1) | Zero semantic guarantees | Full compiler type resolution when LSP compiles cleanly | Default zero-daemon (<15ms), plus opt-in Hybrid LspSemanticAdapter (use_lsp: true / chronos lsp-hydrate): disambiguates obj.method() candidates with graceful AST fallback |
What's New in v1.8.1 & v1.8.0
v1.8.1 Highlights
- Opt-In Hybrid
LspSemanticAdapter&chronos lsp-hydrate: Resolvesrust-analyzer,typescript-language-server(.cmdwrapper on Windows),pyright,gopls,clangd, andjdtlsoverContent-Lengthstdio JSON-RPC with60s/15stimeouts, UTF-16 byte mapping,use_lsppromotion ofobj.method()candidate_sites, and deterministic AST fallback (coverage.completeness = "partial"). - Polyglot
safe_deleteInterface & Override Guards: Blocks unsafe deletions across TypeScript (implements/override), Java (@Override/implements), and Go (structural cross-fileinterfacesatisfaction), in addition to Rust trait impls. - MCP Spec & Token Optimization: Suppresses illegal responses to JSON-RPC notifications, decodes
file://Windows/POSIXrootUris, negotiates MCPprotocolVersionup to2025-11-25, emitsToolAnnotations(readOnlyHint,destructiveHint), and compactschronos_explorepayloads (-69% to -72% estimated tokens and 3x–4x fewer round-trips vs. grep+read inbenchmarks/). - Release Parity & Homebrew Formula: Added
scripts/check_version_sync.pyCI guard andpackaging/homebrew/chronos.rb.
v1.8.0 Core Release
v1.8.0 turns CHRONOS-AGENT into a gated read + edit + refactor + script workspace engine across 7 language families (.ts/.tsx/.js/.jsx, .py, .rs, .go, .c/.cpp, .java):
| Subsystem | v1.8.0 Upgrade |
|---|---|
1. Fresh-Parse AST Editing (chronos_edit_symbol #13 & chronos edit) | Reads current bytes from disk and parses a fresh Tree-sitter CST before every edit (declaration_span vs. full_symbol_span). Deduplicates #[attributes], @decorators, and doc-comments, matches target column indentation, preserves UTF-8 BOM & CRLF/LF via AtomicFileWriter, and enforces a 2-Stage Gate (Stage 1 syntax gate + Stage 2 signature contract & fan_in > 0 check). |
2. Edge-Verified Refactoring (chronos_refactor_symbol #14, chronos rename, chronos delete) | Classifies AST identifiers while skipping comments and string literals, protects module-path prefixes (use crate::math::math;), blocks blocked_ambiguous_rename on candidates/homonyms/unresolved calls without --force, validates syntax on 100% of touched files before transactional rollback-safe commit, and hardens safe_delete against callers, tests, ApiRoutes, entrypoints, pub/export coverage gaps, and Rust trait impls. |
3. Progressive Class/* & Batch chronos_explore (#12) | Supports Class/* wildcard outlines (with per-impl NodeId isolation in Rust), include_body: false signature outlines, depth child expansion, batch queries[], and inline include_blast_radius. |
4. Sandboxed rhai 5D Script Engine (chronos_explore.script, chronos eval, chronos repl) | Embeds rhai (Engine::new_raw(), bounded at 50_000 ops, zero disk/network/shell I/O) with strict dual profiles: ScriptProfile::ReadOnly for MCP & --readonly CLI, and ScriptProfile::FullCli for gated CLI scripts and interactive REPL sessions. |
5. AtomicFileWriter & xxHash64 Deduplication | Transactional multi-file writes roll back all prior modified files on disk error; WorkspaceSession::index_file caches last_indexed_hashes to skip redundant FileWatcher bursts in <0.2ms. |
Previous Releases (v1.7.0, v1.6.0, v1.5.0, v1.4.0, v1.3.0 & v1.2.0)
- v1.7.0: Consolidated
WorkspaceSession, canonicalToolRegistry/McpToolRegistry(zero schema drift), Schema v2GraphRepository,_meta.contract_alertsmiddleware, 24kmax_answer_charsUTF-8 budgeting, and upgraded embedded KuzuDB to single-file0.11.3(cxx-build = 1.0.138) fixing Linux GCC 15 CI aborts. - v1.6.0: Added
chronos_explore, Reverse-BFSverification_surfaces, line-anchoredstructured_findings, 4-Angle Review Audit (Reuse,Efficiency,Simplification,Altitude),<20mslifecycle hooks (chronos hook), and the 20-file multi-agent scaffolder. - v1.5.0: Added
chronos init,chronos agents-md,chronos schemaexporter (OpenAI, Anthropic, Gemini, Codex TOML, MCP), andSECURITY.md. - v1.4.0: Added KuzuDB
xxHash64incremental sync, cross-boundary HTTP route stitching (/{*}), GitCO_CHANGES_WITHco-change mining, single-compileCHRONOS_MUTANT_IDSuper-Mutant evaluation, and offline telemetry hydration (.cpuprofile, Speedscope, Folded Flamegraph, OTLP JSON). - v1.3.0 & v1.2.0: Polyglot 7-language Tree-sitter parser, interprocedural
transitive_loop_depth/ $O(N^2)$ loop scan detection, read-only OpenCypher (chronos_query_graph), BM25 search, Label Propagation clustering, PageRankconfidence_interval, andchronos diff --ci.
Core Architecture
| Component | Responsibility | Crate Path |
|---|---|---|
| Knowledge Graph & Query | Petgraph call/test topology, embedded single-file KuzuDB 0.11.3, OpenCypher, BM25 + Class/* exploration, Git co-change mining | chronos-core/src/graph/ |
| Fresh AST Editor & Refactor | Tree-sitter 7-language parsers, FreshParsedFile trivia spans, AtomicFileWriter, chronos_edit_symbol, chronos_refactor_symbol | chronos-core/src/ast/ |
| Sandboxed Rhai Script Engine | Engine::new_raw() with 50_000 ops ceiling separating ScriptProfile::ReadOnly (MCP) from ScriptProfile::FullCli | chronos-core/src/script/ |
| Contract Broker & Blast Radius | 300ms debounced watcher, signature fingerprinting, PageRank impact scoring, confidence intervals, 4-angle audit, surface tracer | chronos-core/src/{contract,blast_radius}/ |
| Super-Mutant & Telemetry | Graph-selected sandbox mutation runner (CHRONOS_MUTANT_ID), CDP V8 / eBPF adapters, offline .cpuprofile/OTLP hydrator | chronos-core/src/{mutation,telemetry}/ |
Capability Matrix
14 Canonical MCP Tools
chronos-mcp speaks MCP (v2024-11-05) over stdio JSON-RPC 2.0, exposes 14 canonical tools (plus compatibility aliases chronos_replace_symbol_body, chronos_rename_symbol, chronos_safe_delete), enforces --readonly guards, injects _meta.contract_alerts, and caps oversized replies cleanly via max_answer_chars:
| # | Tool Name | Mode | Category | Description |
|---|---|---|---|---|
| 1 | chronos_analyze_file | Read | Ingestion & Audit | Parse source file (7 language families), sync KuzuDB delta, and run 4-Angle Review Audit. |
| 2 | chronos_query_hotspots | Read | Telemetry | Rank runtime bottlenecks, PageRank hubs, and nested loop hotspots. |
| 3 | chronos_blast_radius | Read | Impact & Findings | Compute PageRank blast-radius, verification_surfaces, structured_findings, Git co-changes, and uncertainty intervals. |
| 4 | chronos_mutation_gate | Read | Verification | Execute graph-selected covering tests against Super-Mutant builds. |
| 5 | chronos_contract_status | Read | Contracts | Drain queued Semantic Contract Broker alerts from the Pre-Tool Execution Gate. |
| 6 | chronos_query_graph | Read | Cypher | Run read-only OpenCypher queries over KuzuDB (CALLS, CONTAINS, TESTS, IMPORTS, CO_CHANGES_WITH). |
| 7 | chronos_search_graph | Read | Discovery | Search symbols with BM25 identifier tokenization (camelCase/snake_case), regex, degree, and loop filters. |
| 8 | chronos_get_snippet | Read | Context | Read verbatim start_line..=end_line code with callers, callees, covering tests, and AST metrics. |
| 9 | chronos_get_architecture | Read | Topology | Index workspace incrementally, mine Git co-changes, and extract Label Propagation clusters + hotspots. |
| 10 | chronos_hydrate_telemetry | Read | Telemetry | Hydrate runtime metrics from .cpuprofile, Speedscope/py-spy, Folded Flamegraph, or OTLP JSON. |
| 11 | chronos_generate_agents_md | Read/Preview | Multi-Agent | Synthesize AGENTS.md, CLAUDE.md, GEMINI.md, Antigravity SKILL.md, Cursor .mdc, and hooks (write_to_disk: true blocked under --readonly). |
| 12 | chronos_explore | Read | 1-Call Context | 1-call context engine supporting Class/* wildcards, include_body: false, depth, batch queries[], inline include_blast_radius, and ScriptProfile::ReadOnly Rhai script. |
| 13 | chronos_edit_symbol | Write | AST Editing | Fresh-parse replace_body, insert_before, insert_after with trivia dedup, BOM/CRLF preservation, and 2-Stage gate (alias chronos_replace_symbol_body; disabled in --readonly). |
| 14 | chronos_refactor_symbol | Write / Preview | Refactoring | Edge-verified rename, hardened safe_delete, and preview_usages (verified_edits vs. candidate_sites) with multi-file atomic rollback (aliases chronos_rename_symbol, chronos_safe_delete; --readonly permits preview_usages and dry_run: true). |
Supported AI Clients (chronos init --client all --with-hooks)
| Client / IDE | Generated Files |
|---|---|
| OpenAI Codex CLI | AGENTS.md, .codex/config.toml |
Google Antigravity (agy) | GEMINI.md, .agents/skills/chronos-agent/SKILL.md, .agents/plugins/chronos-agent/, .agents/hooks.json |
| Anthropic Claude Code | CLAUDE.md, .mcp.json, .claude/commands/chronos-audit.md, .claude/settings.json |
| OpenCode, Cursor, Windsurf, Copilot, Cline | opencode.json, .opencode/agent/chronos-auditor.md, .cursor/rules/chronos-5d.mdc, .cursor/mcp.json, .windsurfrules, .windsurf/mcp.json, .github/copilot-instructions.md, .vscode/mcp.json, .clinerules |
Export AI SDK schemas directly for custom agent harnesses:
chronos schema --format responses > openai.json # OpenAI Responses API (14 tools, strict: true)
chronos schema --format anthropic > claude.json # Anthropic Messages API (14 tools, input_schema)
chronos schema --format gemini > gemini.json # Google Gemini / Vertex AI (14 tools, functionDeclarations)
VS Code Extension
Install "CHRONOS Agent" from the Visual Studio Marketplace (chronos-vscode/):
- Incremental Watcher: Re-indexes modified source files on save across all 7 language families and syncs
KuzuDB. - Blast-Radius & Uncertainty HUD: Surfaces composite impact scores, confidence intervals, PageRank hubs, Git co-change partners, and surviving mutants inside VS Code.
CLI Command Suite & Build from Source
Common CLI Commands
# 1. Surgical AST Symbol Edit (with 2-stage syntax & blast-radius gate)
chronos edit charge --file src/billing.rs --op replace_body --code "pub fn charge(a: i32) -> i32 { a * 2 }" --dry-run
# 2. Edge-Verified Multi-File Rename & Hardened Safe Delete
chronos rename compute_tax calculate_vat --file src/billing.rs --dry-run
chronos delete legacy_helper --file src/cleanup.rs
# 3. Embedded Rhai 5D Scripting (One-Shot Eval & Interactive REPL)
chronos eval "hotspots(5)" --readonly --json
chronos repl
# 4. 1-Call Context Explore (Wildcards, Signature Outline & Blast-Radius)
chronos explore "OrderService/*" --no-body --depth 2 --blast-radius
# 5. Full Audit, Architecture, Search, Cypher & Git Diff Gate
chronos audit src/services/orderService.ts
chronos hydrate profile.cpuprofile --json
chronos arch chronos-core/src
chronos query "MATCH (n:ChronosNode) WHERE n.transitive_loop_depth >= 2 RETURN n.name, n.transitive_loop_depth LIMIT 10"
chronos diff --staged --json --ci
Build from Source
# Prerequisites: Rust 1.85+, CMake, C++ compiler (for embedded KuzuDB 0.11.3)
git clone https://github.com/ptai-eng/chronos-agent.git
cd chronos-agent
cargo build --release -j 4
cargo test --workspace -j 4
Security & Local-First Guarantees
CHRONOS-AGENT runs locally inside your workspace with no outbound telemetry or cloud code uploads:
- Workspace Path Jailing: Every read, index, edit, and refactor call canonicalizes paths via
WorkspaceSession::validate_workspace_pathand rejects paths escapingworkspace_root. - Strict
--readonlyMode: Passing--readonlytochronos-mcphides mutating tools (chronos_edit_symbol,chronos_refactor_symbol) fromtools/listand blocks disk writes while preserving read-only previews (preview_usages,dry_run). - Isolated Rhai Sandbox:
ScriptEngineinitializesEngine::new_raw()with zero filesystem, network, process, or env APIs and aborts runaway scripts at50_000operations. MCPchronos_explore.scriptruns underScriptProfile::ReadOnly, which never registers write bindings. - Transactional Integrity & Read-Only Cypher: Disk writes use
AtomicFileWriter(BOM/CRLF preservation + multi-file rollback), OpenCypher queries passvalidate_readonly_cypher, and extracted snippets carry_meta.provenance.untrusted_content. - Opt-In Profiling & Sandbox Testing: Linux eBPF tracepoints, Chrome DevTools WebSocket attachment, and isolated test subprocesses only run when explicitly invoked via profiling or mutation commands. Full threat model details live in
SECURITY.md.
License
Distributed under the MIT License. See LICENSE for details.
ghcr.io/ptai-eng/chronos-agent:1.8.0docker pull ghcr.io/ptai-eng/chronos-agent:1.8.0:undefined