Limps

limps

Local Intelligent MCP Planning Server — A document and planning layer for AI assistants. No subscriptions, no cloud. Point limps at any folder (local, synced, or in git). One shared source of truth across Claude, Cursor, Codex, and any MCP-compatible tool.

Table of Contents

• Quick Start
• Features
• How I Use limps
• Health & Automation
• How You Can Use It
• Why limps?
• Installation
• Upgrading from v2
• Project Setup
• Client Setup
• Transport
• Daemon Management
• CLI Commands
• Configuration
• Environment Variables
• Troubleshooting
• MCP Tools
• Skills & Commands
• Extensions
• Obsidian Compatibility
• Development
• Used in Production
• Creating a feature plan
• Deep Dive
• What is MCP?
• License

Quick Start

# Install globally

npm install -g @sudosandwich/limps

Initialize in your project

cd ~/Documents/my-planning-docs limps init

Start the HTTP daemon

limps server start

→ Daemon starts on http://127.0.0.1:4269/mcp

→ PID file written to OS-standard location

→ Ready for MCP client connections

Generate MCP client config

limps config print --client claude-code

Copy the output to your MCP client config file

That's it. Your AI assistant now has access to your documents via HTTP transport. The folder can be anywhere—local, synced, or in a repo; limps does not require a git repository or a plans/ directory.

Tip: limps server status always includes system-wide daemon discovery. If a project config is found (or passed via --config), it also reconciles the configured project target against that global list.

Features

• Document CRUD + full-text search across any folder of Markdown files
• Plan + agent workflows with status tracking and task scoring
• Next-task suggestions with score breakdowns and bias tuning
• Sandboxed document processing via process_doc(s) helpers
• Multi-client support for Cursor, Claude, Codex, and more
• Extensions for domain-specific tooling (e.g., limps-headless)
• Knowledge graph — Entity extraction, hybrid retrieval, conflict detection, and graph-based suggestions
• Health automation — Staleness detection, code drift checks, status inference, and auto-fix proposals
• Advanced task scoring — Dependency-aware prioritization with per-plan/agent weight overrides
• MCP Registry — Published to the official MCP Registry (registry.modelcontextprotocol.io)

What to know before you start

• Local only — Your data stays on disk (SQLite index + your files). No cloud, no subscription.
• Restart after changes — If you change the indexed folder or config, restart the MCP server (or rely on the file watcher) so the index and tools reflect the current state.
• Daemon management — The HTTP server runs as a background process. Use limps server start, limps server stop, and limps server status to manage the daemon lifecycle. PID files are stored in OS-standard directories for system-wide awareness.
• Sandboxed user code — process_doc and process_docs run your JavaScript in a QuickJS sandbox with time and memory limits; no network or Node APIs.
• One optional network call — limps version --check fetches from the npm registry to compare versions. All other commands (serve, init, list, search, create/update/delete docs, process_doc, etc.) do not contact the internet. Omit version --check if you want zero external calls.

How I Use limps

I use limps as a local planning layer across multiple AI tools, focused on create → read → update → closure for plans and tasks. The MCP server points at whatever directory I want (not necessarily a git repo), so any client reads and updates the same source of truth.

Typical flow:

1. Point limps at a docs directory (any folder, local or synced).
2. Use CLI + MCP tools to create plans/docs, read the current status, update tasks, and close work when done.
3. Add the limps MCP entry to each client config so Cursor/Claude/Codex all see the same plans.

Commands and tools I use most often:

• Create: limps init, create_plan, create_doc
• Read: list_plans, list_agents, list_docs, search_docs, get_plan_status
• Update: update_doc, update_task_status, manage_tags
• Close: update_task_status (e.g., PASS), delete_doc if needed
• Analyze: graph health, graph search, graph check, health check

Full lists are below in "CLI Commands" and "MCP Tools."

How You Can Use It

limps is designed to be generic and portable. Point it at any folder with Markdown files and use it from any MCP-compatible client. No git repo required. Not limited to planning—planning (plans, agents, task status) is one use case; the same layer gives you document CRUD, full-text search, and programmable processing on any indexed folder.

Common setups:

• Single project: One docs folder for a product.
• Multi-project: Each project gets its own .limps/config.json; pass --config to target a specific one.
• Shared team folder: Put plans in a shared location and review changes like code.
• Local-first: Keep everything on disk, no hosted service required.

Key ideas:

• Any folder — You choose the path; if there’s no plans/ subdir, the whole directory is indexed. Use generic tools (list_docs, search_docs, create_doc, update_doc, delete_doc, process_doc, process_docs) or plan-specific ones (create_plan, list_plans, list_agents, get_plan_status, update_task_status, get_next_task).
• One source of truth — MCP tools give structured access; multiple clients share the same docs.

Why limps?

The problem: Each AI assistant maintains its own context. Planning documents, task status, and decisions get fragmented across Claude, Cursor, ChatGPT, and Copilot conversations.

The solution: limps provides a standardized MCP interface that any tool can access. Your docs live in one place—a folder you choose. Use git (or any sync) if you want version control; limps is not tied to a repository.

Installation

npm install -g @sudosandwich/limps

Upgrading from v2

v3 introduces major changes:

HTTP Transport (Breaking Change)

v3 uses HTTP transport exclusively. stdio transport has been removed.

Migration steps:

1. Start the HTTP daemon for each project:

   limps server start --config /path/to/.limps/config.json

1. Update MCP client configs — Replace stdio configs with HTTP transport:

   {

"mcpServers": { "limps-planning-myproject": { "transport": { "type": "http", "url": "http://127.0.0.1:4269/mcp" } } } }

   Use `limps config print` to generate the correct snippet.

Per-Project Configs (Breaking Change)

v3 removes the centralized project registry. If you previously used limps config add, config use, or the --project flag:

1. Run `limps init` in each project directory to create .limps/config.json.
2. Update MCP client configs — Replace --project with HTTP transport config (see above).
3. Remove environment variable — LIMPS_PROJECT no longer exists. Use MCP_PLANNING_CONFIG to override config path.

Removed commands: config list, config use, config add, config remove, config set, config discover, config migrate, config sync-mcp, serve.

Replaced by: limps init + limps server start + limps config print.

Project Setup

Initialize a New Project

cd ~/Documents/my-planning-docs

limps init

This creates .limps/config.json in the current directory and prints MCP client setup instructions.

You can also specify a path:

limps init ~/Documents/my-planning-docs

If the directory contains a plans/ subdirectory, limps uses it. Otherwise, it indexes the entire directory.

Multiple Projects

Each project has its own .limps/config.json. Use --config to target a specific project:

limps plan list --config ~/docs/project-b/.limps/config.json

Client Setup

After running limps init, you need to add a limps entry to your MCP client's config file. Use limps config print to generate the correct snippet for your client, then paste it into the appropriate config file:

limps config print --client cursor

limps config print --client claude-code limps config print --client claude

The output tells you exactly what JSON (or TOML) to add and where the config file lives.

Per-Client Examples

All clients connect to the HTTP daemon. Start the daemon first with limps server start, then configure your client.

Cursor

Add to .cursor/mcp.json in your project:

{

"mcpServers": { "limps-planning-myproject": { "transport": { "type": "http", "url": "http://127.0.0.1:4269/mcp" } } } }

Claude Code

Add to .mcp.json in your project root:

{

"mcpServers": { "limps-planning-myproject": { "transport": { "type": "http", "url": "http://127.0.0.1:4269/mcp" } } } }

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{

"mcpServers": { "limps-planning-myproject": { "transport": { "type": "http", "url": "http://127.0.0.1:4269/mcp" } } } }

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.limps-planning-myproject.transport]

type = "http" url = "http://127.0.0.1:4269/mcp"

ChatGPT

ChatGPT requires a remote MCP server over HTTPS. Deploy limps behind an MCP-compatible HTTPS reverse proxy (nginx, Caddy, etc.) with authentication.

In ChatGPT → Settings → Connectors → Add custom connector:

• Server URL: https://your-domain.example/mcp
• Authentication: Configure as needed for your proxy

Print setup instructions:

limps config print --client chatgpt

Transport

limps v3 uses HTTP transport exclusively via a persistent daemon. This allows multiple MCP clients to share a single server instance, avoiding file descriptor bloat from multiple stdio processes.

Start the HTTP daemon

# Start the daemon

limps server start

Check status (shows uptime, sessions, PID)

limps server status

Stop the daemon

limps server stop

The daemon runs at http://127.0.0.1:4269/mcp by default. Use limps config print to generate the correct MCP client configuration:

limps config print --client claude-code

See Daemon Management for detailed lifecycle documentation.

MCP Client Con