Skip to main content
Glama
CHRONOS-AGENT

CHRONOS-AGENT

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 | iex

macOS (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-hooks

Or 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 (<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

Current Trade-off (v1.8.0)

Zero semantic guarantees

Full compiler type resolution when LSP compiles cleanly

Pure static Tree-sitter (v1.8.0): dynamic obj.method() receivers go to candidate_sites for review instead of guessing; opt-in Hybrid LSP lands in v1.8.1


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 (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.

  • 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

Component

Responsibility

Crate Path

Knowledge Graph &amp; 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 &amp; 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 &amp; 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 &amp; 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 &amp; 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 &amp; 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)

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 &amp; 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.

Available Tools

14 tools
chronos_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

    B3.4/5.0

    Scored across 14 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      7
      1
      MIT