Repository avatar
Other Tools
v1.8.0
active

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 Tactile Hardware Banner

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.

Version 1.8.1 npm @ptai-eng/chronos-mcp Official MCP Registry VS Code Marketplace Rust Edition Tests 157/157 Passing MCP Protocol 14 Tools Local-First Security Glama MCP Score

CHRONOS-AGENT v1.8.0 Terminal Demo: 1-Call Explore, Stage 2 Signature Gate & Edge-Verified Rename

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", "."]
    }
  }
}

CHRONOS-AGENT MCP server on Glama


Table of Contents


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.

AspectBuilt-in Agent Grep / Line EditsDaemon LSP MCPs (e.g. Serena)CHRONOS-AGENT v1.8
Runtime ModelText regex per turnBackground language server daemon per languageSingle Rust binary (<15ms queries, zero daemon)
Symbol Editing SafetyTrusts stale line numbers / diff hunksLSP offsets + text rewriteFresh Tree-sitter re-parse on every write + 2-Stage Gate (syntax_error & blocked_requires_force when signature changes on callers)
Multi-File RenameGlobal text search/replace risks corrupting locals & commentsCompiler/LSP reference listAST identifier classification separating verified_edits (CALLS/TESTS/imports) from candidate_sites (obj.method(), shadowed locals) + atomic rollback
Impact & Test AwarenessNoneCaller references when server is warmKuzuDB graph + Git co-change coupling + Reverse-BFS entrypoints (verification_surfaces) + Mutation testing
Hybrid Disambiguation (v1.8.1)Zero semantic guaranteesFull compiler type resolution when LSP compiles cleanlyDefault 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: Resolves rust-analyzer, typescript-language-server (.cmd wrapper on Windows), pyright, gopls, clangd, and jdtls over Content-Length stdio JSON-RPC with 60s/15s timeouts, UTF-16 byte mapping, use_lsp promotion of obj.method() candidate_sites, and deterministic AST fallback (coverage.completeness = "partial").
  • Polyglot safe_delete Interface & Override Guards: Blocks unsafe deletions across TypeScript (implements / override), Java (@Override / implements), and Go (structural cross-file interface satisfaction), in addition to Rust trait impls.
  • MCP Spec & Token Optimization: Suppresses illegal responses to JSON-RPC notifications, decodes file:// Windows/POSIX rootUris, negotiates MCP protocolVersion up to 2025-11-25, emits ToolAnnotations (readOnlyHint, destructiveHint), and compacts chronos_explore payloads (-69% to -72% estimated tokens and 3x–4x fewer round-trips vs. grep+read in benchmarks/).
  • Release Parity & Homebrew Formula: Added scripts/check_version_sync.py CI guard and packaging/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):

Subsystemv1.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 DeduplicationTransactional 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, canonical ToolRegistry / McpToolRegistry (zero schema drift), Schema v2 GraphRepository, _meta.contract_alerts middleware, 24k max_answer_chars UTF-8 budgeting, and upgraded embedded KuzuDB to single-file 0.11.3 (cxx-build = 1.0.138) fixing Linux GCC 15 CI aborts.
  • v1.6.0: Added chronos_explore, Reverse-BFS verification_surfaces, line-anchored structured_findings, 4-Angle Review Audit (Reuse, Efficiency, Simplification, Altitude), <20ms lifecycle hooks (chronos hook), and the 20-file multi-agent scaffolder.
  • v1.5.0: Added chronos init, chronos agents-md, chronos schema exporter (OpenAI, Anthropic, Gemini, Codex TOML, MCP), and SECURITY.md.
  • v1.4.0: Added KuzuDB xxHash64 incremental sync, cross-boundary HTTP route stitching (/{*}), Git CO_CHANGES_WITH co-change mining, single-compile CHRONOS_MUTANT_ID Super-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, PageRank confidence_interval, and chronos diff --ci.

Core Architecture

CHRONOS-AGENT Architecture Schematic

ComponentResponsibilityCrate Path
Knowledge Graph & QueryPetgraph call/test topology, embedded single-file KuzuDB 0.11.3, OpenCypher, BM25 + Class/* exploration, Git co-change miningchronos-core/src/graph/
Fresh AST Editor & RefactorTree-sitter 7-language parsers, FreshParsedFile trivia spans, AtomicFileWriter, chronos_edit_symbol, chronos_refactor_symbolchronos-core/src/ast/
Sandboxed Rhai Script EngineEngine::new_raw() with 50_000 ops ceiling separating ScriptProfile::ReadOnly (MCP) from ScriptProfile::FullClichronos-core/src/script/
Contract Broker & Blast Radius300ms debounced watcher, signature fingerprinting, PageRank impact scoring, confidence intervals, 4-angle audit, surface tracerchronos-core/src/{contract,blast_radius}/
Super-Mutant & TelemetryGraph-selected sandbox mutation runner (CHRONOS_MUTANT_ID), CDP V8 / eBPF adapters, offline .cpuprofile/OTLP hydratorchronos-core/src/{mutation,telemetry}/

Capability Matrix

CHRONOS-AGENT Capability Radar Benchmark


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 NameModeCategoryDescription
1chronos_analyze_fileReadIngestion & AuditParse source file (7 language families), sync KuzuDB delta, and run 4-Angle Review Audit.
2chronos_query_hotspotsReadTelemetryRank runtime bottlenecks, PageRank hubs, and nested loop hotspots.
3chronos_blast_radiusReadImpact & FindingsCompute PageRank blast-radius, verification_surfaces, structured_findings, Git co-changes, and uncertainty intervals.
4chronos_mutation_gateReadVerificationExecute graph-selected covering tests against Super-Mutant builds.
5chronos_contract_statusReadContractsDrain queued Semantic Contract Broker alerts from the Pre-Tool Execution Gate.
6chronos_query_graphReadCypherRun read-only OpenCypher queries over KuzuDB (CALLS, CONTAINS, TESTS, IMPORTS, CO_CHANGES_WITH).
7chronos_search_graphReadDiscoverySearch symbols with BM25 identifier tokenization (camelCase/snake_case), regex, degree, and loop filters.
8chronos_get_snippetReadContextRead verbatim start_line..=end_line code with callers, callees, covering tests, and AST metrics.
9chronos_get_architectureReadTopologyIndex workspace incrementally, mine Git co-changes, and extract Label Propagation clusters + hotspots.
10chronos_hydrate_telemetryReadTelemetryHydrate runtime metrics from .cpuprofile, Speedscope/py-spy, Folded Flamegraph, or OTLP JSON.
11chronos_generate_agents_mdRead/PreviewMulti-AgentSynthesize AGENTS.md, CLAUDE.md, GEMINI.md, Antigravity SKILL.md, Cursor .mdc, and hooks (write_to_disk: true blocked under --readonly).
12chronos_exploreRead1-Call Context1-call context engine supporting Class/* wildcards, include_body: false, depth, batch queries[], inline include_blast_radius, and ScriptProfile::ReadOnly Rhai script.
13chronos_edit_symbolWriteAST EditingFresh-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).
14chronos_refactor_symbolWrite / PreviewRefactoringEdge-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 / IDEGenerated Files
OpenAI Codex CLIAGENTS.md, .codex/config.toml
Google Antigravity (agy)GEMINI.md, .agents/skills/chronos-agent/SKILL.md, .agents/plugins/chronos-agent/, .agents/hooks.json
Anthropic Claude CodeCLAUDE.md, .mcp.json, .claude/commands/chronos-audit.md, .claude/settings.json
OpenCode, Cursor, Windsurf, Copilot, Clineopencode.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

CHRONOS-AGENT Developer HUD & Telemetry View

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_path and rejects paths escaping workspace_root.
  • Strict --readonly Mode: Passing --readonly to chronos-mcp hides mutating tools (chronos_edit_symbol, chronos_refactor_symbol) from tools/list and blocks disk writes while preserving read-only previews (preview_usages, dry_run).
  • Isolated Rhai Sandbox: ScriptEngine initializes Engine::new_raw() with zero filesystem, network, process, or env APIs and aborts runaway scripts at 50_000 operations. MCP chronos_explore.script runs under ScriptProfile::ReadOnly, which never registers write bindings.
  • Transactional Integrity & Read-Only Cypher: Disk writes use AtomicFileWriter (BOM/CRLF preservation + multi-file rollback), OpenCypher queries pass validate_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.

OCI
ghcr.io/ptai-eng/chronos-agent:1.8.0
Install Command
docker pull ghcr.io/ptai-eng/chronos-agent:1.8.0:undefined
Runtime: docker