# Ctxora Engine > CTXORA Engine — Local-first context engine for coding agents. Index once. Ground every agent. - **Type:** MCP server - **Install:** `agentstack add mcp-nguyentrunghieutcu-ctxora-engine` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [nguyentrunghieutcu](https://agentstack.voostack.com/s/nguyentrunghieutcu) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [nguyentrunghieutcu](https://github.com/nguyentrunghieutcu) - **Source:** https://github.com/nguyentrunghieutcu/ctxora-engine - **Website:** https://ctxora-landing.vercel.app/ ## Install ```sh agentstack add mcp-nguyentrunghieutcu-ctxora-engine ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # CTXORA Engine ### Index once. Ground every agent. **Local-first context engine for coding agents.** [](https://github.com/nguyentrunghieutcu/ctxora-engine/actions/workflows/ci.yml) [](https://www.npmjs.com/package/ctxora) [](https://skills.sh/nguyentrunghieutcu/ctxora-engine) [](https://www.python.org/) [](LICENSE) [](#privacy-and-security) [](docs/PRICING.md) **English** · [Tiếng Việt](README.vi.md) [Website](https://ctxora-landing.vercel.app/) · [Quick start](#quick-start) · [Installation](#installation) · [Agent skills](#agent-skills) · [CLI](#cli-reference) · [MCP](#mcp-tools) · [Security](#privacy-and-security) > [!IMPORTANT] > **Official sources:** use the `ctxora` package on npm or this GitHub repository. The `ctxora-engine` package is not published on PyPI. Third-party packages using the CTXORA name are not maintained or reviewed by this project. CTXORA Engine builds a reusable, local representation of a repository and supplies the right evidence to Codex, Claude Code, Cursor, GitHub Copilot, or any MCP-compatible agent. Source code, indexes, embeddings, graph data, memory, and handoffs remain on your machine. ## Quick start ### Set up your project Run these commands from the repository you want your coding agent to understand: ```bash npx ctxora setup --workspace . npx ctxora index --workspace . npx ctxora install --workspace . --profile claude-code --dry-run npx ctxora install --workspace . --profile claude-code npx ctxora explain --workspace . \ "Where is authentication implemented?" ``` Then restart your coding client. The first two commands create and index the local workspace; `install` connects the MCP server to Claude Code. Use `--profile codex`, `--profile cursor`, or `--profile generic-mcp` for another client. Expected query output is structured JSON containing relevant files, symbols, provenance, coverage diagnostics, and recommended tests when available. If you only want the CLI, run `npx ctxora query --workspace . "your task"`. If setup fails, run `npx ctxora doctor --workspace .` before retrying. ## Why CTXORA? Coding agents often spend tokens rediscovering a repository, select the wrong layer, miss local conventions, or lose context between sessions. Static instruction files help, but they cannot select task-specific evidence. CTXORA adds a local context layer: ```text Repository ↓ scan, parse, chunk Immutable local snapshot ↓ lexical + semantic + symbol + path + graph indexes Context planner ↓ CAG / RAG / long context / graph-augmented retrieval Codex · Claude Code · Cursor · Copilot · MCP clients ``` - **Fewer wrong edits** — retrieve the module, dependency path, and tests related to the task. - **Less repeated prompting** — reuse repository knowledge across agent sessions. - **Agent-neutral context** — one engine serves multiple coding tools. - **Private by default** — no hosted index, remote telemetry, or required cloud account. - **Deterministic evidence** — every retrieved item includes source path and provenance. ## What you get ### Local context engine - AST-aware chunking for Python, JavaScript, and TypeScript, with bounded fallback chunking for other text formats. - Framework-agnostic setup, indexing, retrieval, and MCP startup verified for Python, TypeScript, Flutter, Go, Rust, Java, Kotlin, Swift, PHP, and Ruby repositories. - Hybrid lexical and local semantic retrieval using BM25, TF-IDF/LSA, keyword overlap, symbols, and paths. - Code dependency graph traversal and graph-augmented context selection. - CAG, RAG, hybrid CAG/RAG, long-context, and graph-augmented planning strategies. - Immutable snapshots with candidate validation, atomic promotion, recovery, and incremental refresh. - Workspace-scoped SQLite memory and raw conversation handoffs. - Token budgeting for OpenAI, Anthropic, and Gemini context windows. ### Agent onboarding ```bash ctxora repo-map --workspace . ctxora context-score --workspace . ctxora generate-agents-md --workspace . ctxora generate-copilot-instructions --workspace . ctxora generate-cursor-rules --workspace . ``` Generated instruction files are deterministic and are never overwritten unless `--force` is provided. ### Safety and operations - Canonical workspace-root authorization and symlink-escape rejection. - Secret-like, binary, dependency, VCS, generated-state, and oversized-file exclusions. - Retrieved repository content is always treated as untrusted evidence, never as agent instructions. - Machine-readable diagnostics, context health reports, evaluation gates, and stable CLI exit codes. - Local `ctxora ci` support for indexing changed files between Git refs. ## Installation ### npm / npx — recommended ```bash npx ctxora setup --workspace /path/to/your/project npx ctxora doctor --workspace /path/to/your/project ``` The dependency-free npm launcher bundles the MIT-licensed Python source and installs CTXORA Engine into a versioned local environment. It does not require a global Python package or a cloud account. Python 3.10–3.13 must already be available. Starting with `6.5.0`, interactive npm launcher sessions check for a newer stable release at most once per 24 hours and print a notice only. Disable the check with `CTXORA_NO_UPDATE_CHECK=1`. Updates are never applied silently: ```bash ctxora update check --workspace . ctxora update plan --workspace . ctxora update apply --workspace . --yes ``` Apply is restricted to the validated npm version, verifies the global installation, reapplies CTXORA-owned MCP profiles and unchanged profile-based skill targets, and rolls back on failure. Customized skill selections are reported for manual review. For a persistent shell command: ```bash npm install --global ctxora ctxora setup --workspace /path/to/your/project ``` ### Install from GitHub ```bash python3 -m pip install \ "git+https://github.com/nguyentrunghieutcu/ctxora-engine.git" ``` ### Install from a clone ```bash git clone https://github.com/nguyentrunghieutcu/ctxora-engine.git cd ctxora-engine python3 -m pip install . ctxora doctor --workspace . ``` ### Development environment ```bash python3 -m venv .venv source .venv/bin/activate python -m pip install -e '.[dev]' ``` Requirements: Python 3.10–3.13 and Git. Runtime state is stored under `.ctxora/`; compatible legacy `.harness/` state remains readable during migration. ## Agent skills Install all CTXORA skills from this repository: ```bash npx skills add nguyentrunghieutcu/ctxora-engine ``` Install the curated CTXORA pack: ```bash npx skills add https://www.skills.sh/p/2fCkKUwjcYsPi0WX ``` List or install one skill: ```bash npx skills add nguyentrunghieutcu/ctxora-engine --list npx skills add nguyentrunghieutcu/ctxora-engine --skill ctxora-setup ``` The repository-level pack contains CTXORA's own setup, navigation, repository-context, health, profile, and learning workflows. The current `skills` CLI requires Node.js 22.20 or newer. CTXORA also vendors the current ECC catalog: 286 skills pinned to ECC commit `e04ea0b9cc8248686edf5ac751cadff550e162b8` on September 8, 2026. Start from an ECC profile, inspect it, then customize modules or individual skills: ```bash npx ctxora skills profiles --workspace . npx ctxora skills modules --workspace . npx ctxora skills preview --workspace . --profile developer npx ctxora skills preview --workspace . --profile developer \ --add-module security --remove-skill security-scan npx ctxora skills install --workspace . --profile developer \ --add-module security --remove-skill security-scan ctxora skills install --workspace . --profile developer \ --target codex --target claude --target cursor --target gemini ctxora skills route "Fix React hydration performance" --workspace . --profile developer ``` Skill installation defaults to a shared runtime catalog: `--target all` records one workspace profile and five lightweight receipts without copying the catalog into each host. Use `route_skills` or `prepare_context` to inject only relevant instructions. `--delivery materialized` is an explicit compatibility mode for hosts that require local files; `--prune` is required to migrate legacy copies and removes only unchanged CTXORA-owned skills. Preview never mutates files, and customized skills are never overwritten. See `THIRD_PARTY_NOTICES.md` for provenance and licensing. ### Commands and agent roles CTXORA also ships explicit workflow templates inspired by ECC's command-first entry points: Canonical reusable guidance lives under `skills/`. Start with `ctxora-navigation` when the right workflow is unclear, use `ctxora-workflow-profiles` to select and customize an ECC skill profile, and use `ctxora-continuous-learning` only after a lesson is verified. See `docs/COMMAND-SKILL-MAP.md` for the compact routing map. Skill reranking is project-scoped and outcome-driven. Routed tasks remain visible as fingerprint-only pending entries until `skill_feedback` records a verified result; CTXORA does not infer success from Git changes or store raw task prompts. `ctxora skills learning --workspace .` and the local Console show completed outcomes, pending routes, and active boost/penalty signals. | Command | Use | CTXORA capability | |---|---|---| | `/ctxora:context ` | Retrieve grounded evidence before coding | `plan_context`, `retrieve_context`, `prepare_context` | | `/ctxora:route ` | Rank profile-enabled ECC skills automatically | `route_skills`, `skill_feedback` | | `/ctxora:plan ` | Create an evidence-based implementation plan | `plan_context`, `retrieve_context` | | `/ctxora:review [scope]` | Review a change with repository context | `retrieve_context` | | `/ctxora:health` | Check workspace and index readiness | `doctor`, `context-score`, `inspect` | | `/ctxora:handoff save\|restore` | Continue work across sessions | handoff MCP tools | The templates are included in the npm package under `commands/`. In a Claude Code plugin installation, the namespace is `/ctxora:`. If you copy a file manually into a host command directory, use the host's naming convention; clients without custom slash commands can invoke the same workflow as a normal prompt. The MCP server alone does not register slash commands. #### Enable the slash commands in Claude Code This workflow requires Claude Code installed and authenticated, plus the MCP setup above. The plugin files are included starting with npm `6.3.0` and are also available from a source checkout containing `.claude-plugin/plugin.json`, `commands/`, and `agents/`. Replace both paths below. Start in **your application repository**, not the CTXORA source repository: ```bash cd "/absolute/path/to/your/project" claude --plugin-dir "/absolute/path/to/ctxora-engine" ``` Pass `--plugin-dir` again on subsequent launches. Inside Claude Code, run `/help` to check command discovery and `/mcp` to check that CTXORA is connected. These are separate checks. Then try: ```text /ctxora:plan Add password reset /ctxora:context Trace the token refresh flow /ctxora:review /ctxora:health ``` For the supported Codex or Cursor profile, use `npx ctxora install --workspace . --profile codex` or replace `codex` with `cursor`. Other MCP clients need their own configuration; there is no dedicated Copilot install profile. Installing MCP does not make `/ctxora:*` commands appear automatically. Try this normal chat prompt after connecting: ```text Use CTXORA retrieve_context for this workspace to find the authentication implementation and its tests. Cite the files and propose a plan; do not edit yet. ``` If commands are missing, check the plugin path. If commands appear but tools are unavailable, check MCP connection and run `npx ctxora doctor --workspace .` in your application repository. If retrieval is stale, run `npx ctxora index --workspace . --incremental`. #### Which agent should I use? Choose the role that matches the work: | Need | Role | Use when | |---|---|---| | Ground repository context | `ctxora-context-engineer` | The task spans unfamiliar or multiple files. | | Plan an implementation | `ctxora-planner` | You need files, dependencies, risks, tests, and success criteria before edits. | | Research a question | `ctxora-researcher` | You need repository evidence plus clearly attributed primary sources. | | Review a proposed change | `ctxora-reviewer` | You need findings, not autonomous implementation. | | Maintain setup and session state | `ctxora-maintainer` | You need indexing, diagnostics, memory, or handoffs. | These are role prompts, not separate LLMs. Your host agent remains responsible for edits; CTXORA supplies local context, memory, and handoff tools. Canonical templates are packaged under `src/harness_context/artifacts/canonical/`; `agents/`, `commands/`, and `skills/` are generated compatibility projections for the Claude plugin and npm ecosystem. To request one explicitly in a host that has loaded these agents, say: "Use the ctxora-reviewer agent to review my uncommitted changes; report findings without editing." Otherwise ask the current assistant to perform that role; do not assume a separate agent was launched. Start with `plan` for a feature, implement and run your project's tests, then use `review`. For a bug, reproduce it first and retrieve the relevant code before changing it. ## Connect a coding agent CTXORA can safely edit supported client configuration while preserving unrelated entries: ```bash ctxora profile --workspace . ctxora install --workspace . --profile codex ctxora install --workspace . --profile claude-code ctxora install --workspace . --profile cursor ctxora install --workspace . --profile generic-mcp ``` Use `--dry-run` to preview changes and `--client-config` to target a non-default file. Supported defaults: | Profile | Default configuration | |---|---| | Codex | `~/.codex/config.toml` | | Claude Code | `~/.claude.json` | | Cursor | `~/.cursor/mcp.json` | | Generic MCP | `~/.config/mcp/servers.json` | Manual MCP configuration: ```json { "mcpServers": { "ctxora": { "command": "ctxora", "args": ["run", "--workspace", "/absolute/path/to/project", "--transport", "stdio"], "env": { "CTXORA_ALLOWED_ROOTS": "/absolute/path/to/project", "PYTHONUTF8": "1" } } } } ``` Do not commit client configuration containing personal absolute paths. ## Core workflows ### Understand a repository ```bash ctxora setup --workspace . ctxora index --workspace . ctxora query --workspace . "How does request authentication flow?" ctxora explain --workspace . "Where should token rotation be changed?" ctxora inspect --workspace . snapshot ``` ### Refresh changed files ```bash ctxora index --workspace . --incremental ctxora ci --workspace . --base origin/main --head HEAD ``` ### Run the MCP server ```bash # Recommended local transport ctxora run --workspace . --transport stdio # Local HTTP transport ctxora run --workspace . --transport streamable-http \ --host 127.0.0.1 --port 8765 ``` Non-loopback HTTP binding requires `--allow-external` and must be protected by an authorization layer before production use. ### Export local state ```bash ctxora export --workspace . --output ./ctxora-snapshot.json ctxora doctor --workspace . ctxora repair --workspace . ``` ## CLI reference | Command | Purpose | |---|---| | `setup` | Create local workspace configuration. | | `register` | Register and authorize a workspace. | | `run` | Start CTXORA MCP in the foreground. | | `start`, `status`, `stop` | Manage the local background process. | | `index` | Build or refresh the local snapshot. | | `query` | Return a structured context package. | | `explain` | Explain where and how a change should be made. | | `context-score` | Score repository context readiness. | | `repo-map` | Produce a compact repository map. | | `inspect` | Inspect workspace, snapshot, bundle, or ECC state. | | `doctor`, `repair` | Diagnose or rebuild local state. | | `dashboard` | Open the loopback-only CTXORA Console with redacted vi … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [nguyentrunghieutcu](https://github.com/nguyentrunghieutcu) - **Source:** [nguyentrunghieutcu/ctxora-engine](https://github.com/nguyentrunghieutcu/ctxora-engine) - **License:** MIT - **Homepage:** https://ctxora-landing.vercel.app/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-nguyentrunghieutcu-ctxora-engine - Seller: https://agentstack.voostack.com/s/nguyentrunghieutcu - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.