CtxNest

The Local Brain & Hands for Your AI Coding Agents

CtxNest is a local-first Model Context Protocol (MCP) server that gives your AI coding agents — Claude Code, Cursor, Gemini, Antigravity — a persistent memory and a controlled command surface.

Instead of agents losing context between sessions or inventing their own shell commands, CtxNest provides:

• Brain: A git-backed markdown vault with FTS5 search and surgical section edits.
• Hands: A sandboxed command engine defined by you in ctxnest.json.
• Eyes: A feedback loop that journals results back into the brain.

Badges & Launches

       

The Unique Value

Most AI tools trap context inside their own chat window. CtxNest moves that context to your own SSD, providing six core advantages:

1. Cross-Agent Handoff

• Switch agents mid-project: Claude Code journals a decision; Cursor reads it 5 minutes later.
• Unified command surface: Author your ctxnest.json once; every agent uses the same validated tools and approval gates.
• Multi-agent collaboration: Different agents working on different tasks contribute to the same indexed knowledge base.

2. Cross-Project Awareness

• Global reach: An agent working in Project A can instantly search and read the documentation, context, and states of Project B.
• Shared standards: Solve a problem once, document it, and let your agent apply that solution across all your other projects automatically.

3. Deterministic Context Retrieval

• SQLite FTS5 Power: Instead of unpredictable vector-based RAG, CtxNest uses high-performance full-text indexing for deterministic, local-first context discovery.
• Reliable Discovery: Fast, exact keyword and regex-based search ensures you find what you're looking for without the "hallucination" risk of third-party embedding providers.

4. Token-Optimized Context Economy

• Surgical fetching: Instead of indiscriminately dumping whole directories into the LLM's context window, CtxNest provides tools to fetch specific file outlines, sections, or targeted search excerpts.
• Budget awareness: Every tool response includes est_tokens so agents can smartly budget what they pull into memory.

5. Separation of Code and Context

• The "Context.md" Killer: Stop littering your source tree with CONTEXT.md or AI_NOTES.md files that clutter your PRs and get stale.
• Global Knowledge Vault: Keep your main codebase pristine. Architectural decisions, agent journals, and cross-project standards live in a separate, dedicated global vault accessible by any agent instance.

6. Compounding Intelligence

• Continuous learning: Through the "Eyes" and journaling system, your AI agents document their decisions, successes, and mistakes.
• Smarter next time: A problem solved today is saved in the Brain, meaning tomorrow's session starts with the benefit of yesterday's experience.

---

Architecture: Brain → Hands → Eyes

CtxNest builds a closed feedback loop that makes every turn smarter than the last.

1. Brain — The Context Engine

A markdown knowledge vault optimized for context-window economy.

• FTS5 Search: Instant local keyword search.
• Surgical Edits: Tools for reading and updating specific markdown sections without pulling entire files.
• Token-Aware: Every response includes est_tokens and size_bytes so agents can budget their context.

2. Hands — The Command Engine

A project-defined command surface that replaces "unrestricted shell access" with a sandboxed contract.

• Explicit boundaries: You declare exactly what an agent can do via ctxnest.json. There is no unrestricted shell access.
• Sandboxed: Locked working directory, clean environment, and ring-buffered output.
• Human-in-the-loop: High-risk commands can require a cryptographic one-time token, pausing execution until you explicitly approve it.

3. Eyes — The Feedback Engine

Closes the loop by capturing Hands' output and journaling learnings back into the Brain.

• Live Observation: Tools like whats_new and diff_against_disk let agents see what actually changed.
• Journaling: journal_append creates a timestamped record of decisions and results.

---

How it Works in Practice

Imagine you are switching from Claude Code to Cursor mid-way through a feature.

The Problem: The "Context Gap"

• Claude Code knows why you chose that specific library.
• Cursor doesn't. You have to copy-paste or re-explain everything.
• CONTEXT.md files help, but they get stale, they clutter your PRs, and they don't capture live decisions.

The CtxNest Solution

1. Journaling: As Claude Code works, it calls journal_append to log its decisions and the "why" behind the code.
2. Persistence: Those logs are saved in your local CtxNest brain, not the chat window.
3. Seamless Handoff: When you open Cursor, it immediately sees the recent journal entries and architectural state via the CtxNest MCP.
4. Zero Re-explanation: Cursor "wakes up" with the exact same context Claude had.

---

How CtxNest Compares

CtxNest doesn't try to replace your favorite agent; it gives it a better body.

Capability	Standard AI Agents	CtxNest + Hands
Context Persistence	Volatile / Session-bound	Local SSD (SQLite FTS5)
Command Surface	Hardcoded by tool vendor	User-defined JSON contract
Execution Security	Implicit / Opaque	Explicit Sandbox (No-shell, strict env)
Agent Handoff	Manual copy-paste	Automated cross-agent state
Storage & Sync	Cloud-managed	Local-first / Git-synchronized

---

Quick Start (5-Minute Trial)

1. Run the MCP Server (No Install)

The fastest way to try CtxNest is via npx. Add this to your MCP client configuration (e.g., mcpServers.json):

{
  "mcpServers": {
    "ctxnest": {
      "command": "npx",
      "args": ["-y", "ctxnest-mcp"],
      "env": {
        "CTXNEST_DATA_DIR": "/absolute/path/to/your/knowledge-vault"
      }
    }
  }
}

2. Run the Dashboard (Docker)

For the full "Obsidian-meets-Terminal" UI, download the compose file, edit your volume mounts and environment variables (e.g., project paths), and run:

curl -fsSL https://raw.githubusercontent.com/safiyu/ctxnest/main/docker-compose.hub.yml -o docker-compose.yml
# Important: Open docker-compose.yml and edit the volumes section 
# to mount your projects directory so the agent can see them.
docker compose up -d

The UI lands at http://localhost:3000.

---

Demo & Walkthrough

In this demo:

• System audit and web clipping.
• Local RAG and context gathering.
• The Brain/Hands/Eyes loop in action.

No-install demo: Try the MCP endpoints interactively right from your browser on the Glama CtxNest page.

---

Project Status & Transparency

Why the high version number on a fresh repository? If you look at the commit history, you might wonder how a repository with so few commits reached its current major version.

CtxNest wasn't built over a weekend. It began over a year ago as a private, monolithic toolchain used to manage complex, multi-agent coding workflows. The versioning reflects its true architectural maturity.

Recently, I undertook a major effort to industrialize and modularize this engine, restructuring it into the three core pillars you see today: Brain, Hands, and Eyes. This process involved decoupling the core from private infrastructure and moving to a clean, open-source monorepo. The condensed git history is the result of this clean extraction—leaving behind internal legacy commits to publish only the battle-tested, production-ready framework available today.

---

Features Breakdown

Brain

• Global vault with two-way git sync.
• 46 MCP tools tuned for context economy.
• Batch operations (up to 500 files/call), grep, and regex support.
• Web clipping with auth-wall detection.
• Full git-backed versioning: get_history, get_diff, restore_file.

Hands

• Project-specific ctxnest.json tools map.
• Strict sandbox: realpath-verified CWD, stripped PATH, and hard timeouts.
• ReDoS-proof parameter validation via re2.
• CSPRNG-bound confirmation tokens for high-risk commands.

Dashboard

• Built-in /docs page with a searchable catalogue of all 4core tools.
• Form-based ctxnest.json editor with live validation.
• Real-time status bar streaming git activity over WebSockets.

---

[!TIP] Deleting a project file in CtxNest only un-indexes it from the AI's memory. Your physical source code is never touched.

---

Contributing

CtxNest is a project for developers, by developers. If you'd like to contribute new tools, improve the core engine, or refine the dashboard, please see our CONTRIBUTING.md for architecture guidelines and local setup instructions.

Built with care for the future of agentic coding. License: Apache-2.0