CHRONOS-AGENT
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CHRONOS-AGENT safely rename parse_config to load_config and show blast radius"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
30-Second Quickstart
Install prebuilt binaries (chronos CLI + chronos-mcp server) without compiling C++/Rust toolchains:
Windows (PowerShell):
irm https://raw.githubusercontent.com/ptai-eng/chronos-agent/main/scripts/install.ps1 | iexmacOS (Apple Silicon) & Linux (x64):
curl -fsSL https://raw.githubusercontent.com/ptai-eng/chronos-agent/main/scripts/install.sh | sh(Rust users with cargo-binstall can also install prebuilt release archives via cargo binstall --git https://github.com/ptai-eng/chronos-agent chronos-cli chronos-mcp.)
Bootstrap configs for Codex, Antigravity, Claude Code, Cursor, OpenCode, Windsurf, Copilot, and Cline in any workspace:
cd your-project
chronos init --client all --with-hooksOr drop chronos-mcp directly into any MCP client config:
{
"mcpServers": {
"chronos-agent": {
"command": "chronos-mcp",
"args": ["--workspace", "."]
}
}
}Related MCP server: Cordyceps Search
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.
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 ( |
Symbol Editing Safety | Trusts stale line numbers / diff hunks | LSP offsets + text rewrite | Fresh Tree-sitter re-parse on every write + 2-Stage Gate ( |
Multi-File Rename | Global text search/replace risks corrupting locals & comments | Compiler/LSP reference list | AST identifier classification separating |
Impact & Test Awareness | None | Caller references when server is warm | KuzuDB graph + Git co-change coupling + Reverse-BFS entrypoints ( |
Current Trade-off ( | Zero semantic guarantees | Full compiler type resolution when LSP compiles cleanly | Pure static Tree-sitter ( |
What's New in v1.8.0
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 ( | Reads current bytes from disk and parses a fresh Tree-sitter CST before every edit ( |
2. Edge-Verified Refactoring ( | Classifies AST identifiers while skipping comments and string literals, protects module-path prefixes ( |
3. Progressive | Supports |
4. Sandboxed | Embeds |
5. | Transactional multi-file writes roll back all prior modified files on disk error; |
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 |
|
|
Fresh AST Editor & Refactor | Tree-sitter 7-language parsers, |
|
Sandboxed Rhai Script Engine |
|
|
Contract Broker & Blast Radius | 300ms debounced watcher, signature fingerprinting, PageRank impact scoring, confidence intervals, 4-angle audit, surface tracer |
|
Super-Mutant & Telemetry | Graph-selected sandbox mutation runner ( |
|
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 |
| Read | Ingestion & Audit | Parse source file (7 language families), sync KuzuDB delta, and run 4-Angle Review Audit. |
2 |
| Read | Telemetry | Rank runtime bottlenecks, PageRank hubs, and nested loop hotspots. |
3 |
| Read | Impact & Findings | Compute PageRank blast-radius, |
4 |
| Read | Verification | Execute graph-selected covering tests against Super-Mutant builds. |
5 |
| Read | Contracts | Drain queued Semantic Contract Broker alerts from the Pre-Tool Execution Gate. |
6 |
| Read | Cypher | Run read-only OpenCypher queries over KuzuDB ( |
7 |
| Read | Discovery | Search symbols with BM25 identifier tokenization ( |
8 |
| Read | Context | Read verbatim |
9 |
| Read | Topology | Index workspace incrementally, mine Git co-changes, and extract Label Propagation clusters + hotspots. |
10 |
| Read | Telemetry | Hydrate runtime metrics from |
11 |
| Read/Preview | Multi-Agent | Synthesize |
12 |
| Read | 1-Call Context | 1-call context engine supporting |
13 |
| Write | AST Editing | Fresh-parse |
14 |
| Write / Preview | Refactoring | Edge-verified |
Supported AI Clients (chronos init --client all --with-hooks)
Client / IDE | Generated Files |
OpenAI Codex CLI | |
Google Antigravity ( |
|
Anthropic Claude Code |
|
OpenCode, Cursor, Windsurf, Copilot, Cline |
|
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 --ciBuild 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 4Security & 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.
Available Tools
14 toolschronos_analyze_fileA
Parse a source file (.ts, .tsx, .js, .py, .rs, .go, .c, .cpp, .java) with CHRONOS's polyglot AST engine and insert all symbols, call edges, cross-language HTTP routes, test edges, and loop/complexity metrics into the 4D Knowledge Graph.
Inputs: file_path (required), max_answer_chars.
chronos_blast_radiusA
Analyze the blast-radius (change impact) of modifying a specific function or symbol. Returns a risk zone (SAFE/MEDIUM/HIGH/CRITICAL), PageRank centrality, Git temporal co-change partners, confidence interval, coverage completeness, and residual unknowns.
Inputs: symbol_name (required), detail, file_path, max_answer_chars, +1 more.
chronos_contract_statusB
Drain the Semantic Contract Broker's Pre-Tool Execution Gate. Returns any pending contract violation alerts detected since the last call.
Inputs: watch_dir, max_answer_chars.
chronos_edit_symbolA
Perform surgical AST-bounded edits (replace_body, insert_before, insert_after) against a fresh disk parse with leading trivia deduplication, indentation/CRLF/BOM preservation, and a 2-stage Tree-sitter syntax + contract blast-radius gate (blocked_requires_force on breaking signature changes with callers unless force=true).
Inputs: file (required), symbol (required), new_code (required), operation (required), +3 more.
chronos_exploreA
1-Call Subagent Context Engine (<15ms). Answers code exploration questions in a single call by returning the top BM25/regex matching symbols, wildcard Class/* outlines, signature-only views (include_body=false), inline blast-radius, read-only Rhai 5D scripts, caller/callee chains, verification surfaces, and 4-angle review diagnostics.
Inputs: depth, query, script, queries, +6 more.
chronos_generate_agents_mdB
Synthesize live, data-driven context rules, skills, and MCP configs from the 5D Knowledge Graph (AGENTS.md, CLAUDE.md, GEMINI.md, .agents/skills/chronos-agent/SKILL.md, .cursor/rules/chronos-5d.mdc) for OpenAI Codex CLI, Google Antigravity, Claude Code, OpenCode, Cursor, Windsurf, Copilot, and Cline.
Inputs: target, auto_index, with_hooks, output_path, +4 more.
chronos_get_architectureA
Get a high-level architecture overview: community clusters (Label Propagation + Cohesion score), language breakdown, entry points, top PageRank hubs, and hidden O(N^2) algorithmic hotspots.
Inputs: path, auto_index, max_answer_chars.
chronos_get_snippetB
Read the verbatim source code (start_line..=end_line) of a function/class from disk along with its callers, callees, covering tests, PageRank, and AST complexity metrics.
Inputs: symbol_name (required), file_path, max_answer_chars.
chronos_hydrate_telemetryB
Hydrate the 4th Dimension (runtime telemetry) of the ChronosGraph from an offline profiler artifact (V8 .cpuprofile JSON, Speedscope/py-spy JSON, Folded Stack Flamegraph text, or OpenTelemetry OTLP trace JSON).
Inputs: profile_path, profile_content, max_answer_chars.
chronos_mutation_gateB
Run targeted mutation testing on a specific file using CHRONOS's Mutation Arena. Generates mutants, selects covering tests via 4D graph, runs them in parallel sandboxes, and returns the mutation score.
Inputs: file_path (required), strict, test_command, max_answer_chars.
chronos_query_graphA
Execute a Read-Only Cypher query directly against the embedded KuzuDB 4D Knowledge Graph. Every ChronosNode has properties: id, name, qualified_name, kind, file, start_line, end_line, start_byte, end_byte, cognitive_load, cyclomatic, fan_in, fan_out, param_count, sloc, loop_count, loop_depth, transitive_loop_depth, linear_scan_in_loop, alloc_in_loop, is_recursive, is_hydrated, exec_time_p50, exec_time_p99, invocation_count, cpu_percent, is_hot_path, is_bottleneck. Relationship tables: CALLS, CONTAINS, TESTS, IMPORTS, CO_CHANGES_WITH.
Inputs: query (required), max_rows, max_answer_chars.
chronos_query_hotspotsB
Query the 4D Knowledge Graph for the top N performance bottlenecks and hot-path functions (using live telemetry or PageRank + O(N^2) loop fallback).
Inputs: top_n, filter, max_answer_chars.
chronos_refactor_symbolA
Perform graph-edge-verified multi-file refactoring (preview_usages, rename, safe_delete). Separates verified CALLS/TESTS/import edits from ambiguous member-access/shadowed candidate sites, enforces multi-file syntax validation + atomic rollback, and guards public/entrypoint/trait-impl deletions.
Inputs: action (required), symbol (required), file, force, +3 more.
chronos_search_graphC
Search the 4D Knowledge Graph using BM25 ranked identifier tokenization (splits camelCase/snake_case), regex pattern matching, degree filtering, and nested-loop complexity filtering.
Inputs: kind, limit, query, offset, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools have distinct roles (analyze, edit, refactor, telemetry hydration, mutation gate), but chronos_explore is explicitly a one-call superset bundling BM25/regex matching, signature views, blast-radius, and caller chains, which overlaps heavily with chronos_search_graph, chronos_get_snippet, and chronos_blast_radius. chronos_query_hotspots vs chronos_get_architecture (which also reports O(N^2) hotspots) and chronos_query_graph vs chronos_search_graph are also easy to confuse despite helpful descriptions.
All names share the chronos_ prefix and snake_case, which is strong, but verb styles mix: verb_noun (analyze_file, query_graph, get_snippet, edit_symbol) alongside bare noun phrases (blast_radius, mutation_gate, contract_status) and one bare verb (explore). Still predictable enough to read correctly at a glance.
14 tools for a code-graph analysis engine covering ingest, query, impact, refactor, testing, and doc generation is well-scoped and each tool clearly earns its place. Slightly on the heavy side but no obvious filler.
CRUD-like lifecycle on symbols is covered (analyze, read, edit, refactor/delete) and the graph query surface is rich, but there is no batch/directory ingest (analyze_file is one file per call) and no way to invalidate or re-index stale graph nodes after external file deletion, which are real gaps for this domain.
Maintenance
Related MCP Connectors
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Stateless TS/JS compiler facts for agents: references, imports, impact. No repo index or OAuth.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceProvides efficient code navigation and graph-based analysis for AI agents, enabling symbol resolution, callers, implementations, and type schemas with minimal token usage.-
- FlicenseNot gradedqualityBmaintenanceEnables developer agents to perform semantic codebase search, dependency and impact analysis, cross-file refactoring, and full-stack API tracing through a unified query DSL over a high-performance graph engine.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents and terminal users to query codebases for callers, impact, tests, dependencies, and refactor previews using static AST analysis, with every match accounted for and uncertain relationships clearly marked.1,067 npm2MIT
- AlicenseAqualityCmaintenanceEnables AI coding agents to index a workspace into AST symbol graphs and retrieve exact function or class slices, trace callers and blast radius, and apply syntax-safe symbol patches without dumping whole files into context.71MIT