New:Microsoft Teams Notifications Are Now Available in Socket.Learn more
Get Started

@sudosandwich/limps

Package Overview
Dependencies
Maintainers
1
Versions
33
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@sudosandwich/limps

Local Intelligent MCP Planning Server - AI agent plan management

Source
npmnpm
Version
3.1.1
Version published
Weekly downloads
59
-6.35%
Maintainers
1
Weekly downloads
 
Created
Source

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.

npm License: MIT Tests Coverage MCP Badge

limps in action

Table of Contents

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 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 status-server shows the status of the current project if a config is found in the working directory (or passed via --config). Run it from a directory where no limps config can be resolved to list all running limps daemons on your system.

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 start, limps stop, and limps status-server to manage the daemon lifecycle. PID files are stored in OS-standard directories for system-wide awareness.
  • Sandboxed user codeprocess_doc and process_docs run your JavaScript in a QuickJS sandbox with time and memory limits; no network or Node APIs.
  • One optional network calllimps 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:

  • Point limps at a docs directory (any folder, local or synced).
  • Use CLI + MCP tools to create plans/docs, read the current status, update tasks, and close work when done.
  • 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:

  • Start the HTTP daemon for each project:

    limps start --config /path/to/.limps/config.json
    
  • 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:

  • Run limps init in each project directory to create .limps/config.json.
  • Update MCP client configs — Replace --project <name> with HTTP transport config (see above).
  • Remove environment variableLIMPS_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 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 list-plans --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 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 start

# Check status (shows uptime, sessions, PID)
limps status-server

# Stop the daemon
limps 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 Configuration

All clients use HTTP transport. Example config:

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

Server Config Options

Customize the HTTP server by adding a "server" section to your config.json:

OptionDefaultDescription
port4269HTTP listen port
host127.0.0.1Bind address
maxSessions100Maximum concurrent MCP sessions
sessionTimeoutMs1800000Session idle timeout in ms (30 min)
corsOrigin"" (none)CORS origin ("", "*", or a URL)
maxBodySize10485760Max request body in bytes (10 MB)
rateLimit100 req/minRate limit per client IP

Example custom server config:

{
  "server": {
    "port": 8080,
    "host": "0.0.0.0"
  }
}

Note: PID files are stored in OS-standard application directories:

  • macOS: ~/Library/Application Support/limps/pids/
  • Linux: $XDG_DATA_HOME/limps/pids/ or ~/.local/share/limps/pids/
  • Windows: %APPDATA%/limps/pids/

This enables limps status-server to perform system-wide daemon discovery when no project configuration can be resolved; when a limps config is found for the current directory, the CLI runs in project mode and reports status for that project instead.

  • Remote clients: Use an MCP-compatible HTTPS proxy for remote clients (e.g., ChatGPT).

Daemon Management

limps v3 uses a persistent HTTP daemon with system-wide awareness. PID files are stored in OS-standard directories, allowing you to manage and discover daemons from any directory on your system.

PID File Locations

PID files are stored in platform-specific application data directories:

macOS:

~/Library/Application Support/limps/pids/

Linux:

$XDG_DATA_HOME/limps/pids/
# or if XDG_DATA_HOME is not set:
~/.local/share/limps/pids/

Windows:

%APPDATA%/limps/pids/

Each PID file is named by port number (limps-{port}.pid) to enable system-wide discovery. Example PID file structure:

{
  "pid": 12345,
  "port": 4269,
  "host": "127.0.0.1",
  "startedAt": "2026-02-08T12:00:00.000Z",
  "configPath": "/path/to/project/.limps/config.json"
}

This port-based naming allows limps status-server to find all running daemons across different projects without needing a config file.

Starting the Daemon

Background mode (default):

limps start
# → Daemon starts on http://127.0.0.1:4269/mcp
# → PID file written to OS-standard location
# → Process detaches and runs in background

Foreground mode (debugging):

limps start --foreground
# → Runs in foreground (blocks terminal)
# → Logs appear in stderr
# → Useful for debugging startup issues
# → Still creates PID file for discovery

Custom port/host (via config):

Configure server.port and server.host in your .limps/config.json:

{
  "server": {
    "port": 8080,
    "host": "0.0.0.0"
  }
}

Then start normally:

limps start
# → Starts using server.port/server.host from config
# → PID file: limps-8080.pid

The start command performs health verification by polling the /health endpoint for up to 5 seconds, issuing repeated HTTP requests. Each individual health-check request has its own shorter timeout (for example, ~1000ms). If any request fails during this window, you'll see one of these error codes:

  • TIMEOUT — A single health-check HTTP request exceeded its per-request timeout (e.g., ~1000ms). The daemon may be slow to start or system resources may be constrained. Try limps start --foreground to see logs.
  • NETWORK_ERROR — Cannot connect to daemon. Port may be blocked or already in use by another process.
  • NON_200_STATUS — Health endpoint returned a non-200 status code. Check daemon logs with foreground mode.
  • INVALID_RESPONSE — Health endpoint responded, but the response was invalid or could not be parsed as expected (for example, malformed or missing required fields).

Checking Daemon Status

Project mode (when config is found):

# From within a project directory with .limps/config.json
limps status-server
# limps server is running
# PID: 12345 | 127.0.0.1:4269
# Uptime: 2h 15m
# Sessions: 3

# Or specify config explicitly
limps status-server --config /path/to/.limps/config.json

System-wide discovery (when no config is found):

# From a directory without a limps config
cd /tmp
limps status-server
# Found 2 running daemons:
# 127.0.0.1:4269 (PID 12345)
#   Uptime: 2h 15m | Sessions: 3
# 127.0.0.1:8080 (PID 67890)
#   Uptime: 45m 30s | Sessions: 1

When limps status-server cannot resolve a config file in the current directory (and no --config is provided), it scans the system PID directory and reports all running limps daemons. When a config is found, it shows only that project's daemon status.

Stopping the Daemon

# From the project directory (where your .limps config lives):
limps stop
# → Gracefully shuts down daemon
# → Closes all MCP sessions
# → Stops file watchers
# → Removes PID file
# → Process exits

# Or from any directory, by specifying the config explicitly:
limps stop --config /path/to/.limps/config.json

The stop command is project-specific and resolves the config to determine which daemon to stop. The daemon performs a graceful shutdown by:

  • Closing all active MCP sessions
  • Shutting down file watchers
  • Removing the PID file
  • Exiting the process

Port Conflicts

If you try to start a daemon on a port that's already in use, limps will detect the conflict and provide resolution guidance:

limps start
# Error: Port 4269 is already in use.
# Process using port: node (PID 12345)
# Command: /usr/local/bin/node /usr/local/bin/limps start
#
# To stop the process: kill 12345
# Or use a different port: limps start --port <port>

On systems with lsof available (macOS, Linux), limps can identify which process is using the port and show its command line. If lsof is not available, you'll see a simpler error message suggesting a different port.

Foreground Mode

Use foreground mode for debugging, Docker deployments, or CI/CD pipelines:

limps start --foreground

Use cases:

  • Debugging — See server logs in real-time to diagnose startup issues
  • Docker — Keep container alive with the daemon as the main process
  • CI/CD — Run tests against a limps daemon without background processes

Behavior differences from background mode:

  • Logs to stderr instead of being silent
  • Blocks the terminal (press Ctrl+C to stop)
  • Still creates a PID file for discovery by other processes
  • Responds to SIGINT (Ctrl+C) and SIGTERM for graceful shutdown

Health Endpoint

The HTTP daemon exposes a /health endpoint for monitoring and health checks:

curl http://127.0.0.1:4269/health

Example response:

{
  "status": "ok",
  "sessions": 3,
  "uptime": 8145,
  "pid": 12345,
  "sessionTimeoutMs": 1800000
}

HTTP status codes:

  • 200 — Daemon is healthy and accepting connections
  • 429 — Rate limit exceeded (rate limiter may return this before the request reaches /health)

Use this endpoint for:

  • Monitoring daemon health in scripts or dashboards
  • Verifying daemon is running before connecting MCP clients
  • Automated health checks in orchestration tools (Kubernetes, Docker Compose)

Multiple Daemons

You can run multiple limps daemons on different ports for different projects by configuring different ports in each project's config:

# Project A with default port (4269)
cd ~/projects/project-a
# .limps/config.json has server.port: 4269 (or uses default)
limps start
# → Running on http://127.0.0.1:4269/mcp

# Project B with custom port (8080)
cd ~/projects/project-b
# .limps/config.json has server.port: 8080
limps start
# → Running on http://127.0.0.1:8080/mcp

Each daemon has its own PID file:

  • limps-4269.pid — Project A
  • limps-8080.pid — Project B

Discover all running daemons (run from a directory without a limps config):

cd /tmp
limps status-server
# Found 2 running daemons:
# 127.0.0.1:4269 (PID 12345)
#   Uptime: 2h 15m | Sessions: 3
# 127.0.0.1:8080 (PID 67890)
#   Uptime: 45m 30s | Sessions: 1

Each MCP client can connect to different daemons by configuring different URLs in their config files.

CLI Commands

Viewing Plans

limps list-plans              # List all plans with status
limps list-agents <plan>      # List agents in a plan
limps status <plan>           # Show plan progress summary
limps next-task <plan>        # Get highest-priority available task

Project Management

limps init [path]             # Initialize new project
limps start                   # Start HTTP daemon (background by default)
limps start --foreground      # Start in foreground (debugging mode)
limps stop                    # Stop HTTP daemon
limps status-server           # Show daemon status (current project or all daemons)
limps config show             # Display current config
limps config print            # Print MCP client config snippets

Health & Automation

limps health check              # Aggregate all health signals
limps health staleness [plan]   # Find stale plans/agents
limps health drift [plan]       # Detect file reference drift
limps health inference [plan]   # Suggest status updates
limps proposals list             # List auto-fix proposals
limps proposals apply <id>       # Apply a proposal
limps proposals apply-safe       # Apply all safe proposals

Knowledge Graph

limps graph reindex              # Build/rebuild graph
limps graph health               # Graph stats and conflicts
limps graph search <query>       # Search entities
limps graph trace <entity>       # Trace relationships
limps graph entity <id>          # Entity details
limps graph overlap              # Find overlapping features
limps graph check [type]         # Run conflict detection
limps graph suggest <type>       # Graph-based suggestions
limps graph watch                # Watch and update incrementally

Scoring & Repair

limps score-all <plan>           # Score all agents in a plan
limps score-task <task-id>       # Score a single task
limps repair-plans [--fix]       # Check/fix agent frontmatter

Configuration

Config lives at .limps/config.json in your project directory, created by limps init.

Config Options

{
  "plansPath": "./plans",
  "docsPaths": ["."],
  "fileExtensions": [".md"],
  "dataPath": ".limps/data",
  "extensions": ["@sudosandwich/limps-headless"],
  "tools": {
    "allowlist": ["list_docs", "search_docs"]
  },
  "scoring": {
    "weights": { "dependency": 40, "priority": 30, "workload": 30 },
    "biases": {}
  }
}
OptionDescription
plansPathDirectory for structured plans (NNNN-name/ with agents)
docsPathsAdditional directories to index
fileExtensionsFile types to index (default: .md)
dataPathSQLite database location
toolsTool allowlist/denylist filtering
extensionsExtension packages to load
scoringTask prioritization weights and biases
serverHTTP daemon settings (port, host, CORS, sessions, timeout)
graphKnowledge graph settings (e.g., entity extraction options)
retrievalSearch recipe configuration for hybrid retrieval

Environment Variables

VariableDescriptionExample
MCP_PLANNING_CONFIGPath to config file (overrides default discovery)MCP_PLANNING_CONFIG=./my-config.json limps serve
LIMPS_ALLOWED_TOOLSComma-separated allowlist; only these tools are registeredLIMPS_ALLOWED_TOOLS="list_docs,search_docs"
LIMPS_DISABLED_TOOLSComma-separated denylist; tools to hideLIMPS_DISABLED_TOOLS="process_doc,process_docs"

Precedence: config.tools overrides env vars. If allowlist is set, denylist is ignored.

Troubleshooting

Daemon Won't Start

"Port already in use" error:

If you see this error, another process is using the port:

limps start
# Error: Port 4269 is already in use.
# Process using port: node (PID 12345)

Resolution:

  • Kill the existing process: kill 12345
  • Or use a different port: limps start --port 8080
  • Check if it's another limps daemon: limps status-server (if so, use limps stop first)

"Daemon may have failed to start" error:

If the daemon starts but doesn't respond to health checks:

limps start
# Error: Daemon may have failed to start. Check logs or try: limps start --foreground

Resolution:

  • Run in foreground to see logs: limps start --foreground
  • Check for permission issues: Ensure you have write access to the PID directory
  • Verify port is accessible: Try curl http://127.0.0.1:4269/health
  • Enable debug logging: DEBUG=1 limps start --foreground

Permission issues with PID directory:

If you can't create PID files:

# macOS
ls -la ~/Library/Application\ Support/limps/pids/

# Linux
ls -la ~/.local/share/limps/pids/

# Windows
dir %APPDATA%\limps\pids

Ensure the directory exists and you have write permissions. If not, create it manually:

# macOS
mkdir -p ~/Library/Application\ Support/limps/pids

# Linux
mkdir -p ~/.local/share/limps/pids

# Windows
mkdir %APPDATA%\limps\pids

Health Check Failures

TIMEOUT error:

The daemon did not respond within the configured timeout. Each health-check request has its own timeout (for example, 1000ms during the final limps start check and 3000ms for status-server), and during startup limps will poll for up to about 5 seconds before reporting "Daemon may have failed to start".

Common causes:

  • System resource constraints (high CPU/memory usage)
  • Slow filesystem (especially for index initialization)
  • Large document corpus requiring time to index

Resolution:

  • Check system resources: top or Activity Monitor
  • Wait a bit longer and retry: limps status-server
  • Run in foreground to see progress: limps start --foreground

NETWORK_ERROR:

Cannot establish connection to the daemon.

Common causes:

  • Port is blocked by firewall
  • Daemon crashed after starting
  • Incorrect host/port configuration

Resolution:

  • Verify daemon is running: limps status-server
  • Check firewall settings for port 4269
  • Try curl http://127.0.0.1:4269/health manually
  • Check daemon logs: limps start --foreground

Stale PID Files

limps automatically cleans up stale PID files when:

  • Running limps status-server (discovers and removes stale files)
  • Running limps start (removes stale file for the target port)
  • The daemon shuts down gracefully with limps stop

If you need to manually clean up PID files:

# macOS
rm ~/Library/Application\ Support/limps/pids/limps-*.pid

# Linux
rm ~/.local/share/limps/pids/limps-*.pid

# Windows
del %APPDATA%\limps\pids\limps-*.pid

When to manually clean up:

  • After a system crash or forced shutdown
  • If limps start reports a daemon is running but it's not
  • Before uninstalling limps

Multiple Daemons Conflict

If you accidentally try to start a second daemon on the same port:

limps start
# Error: limps daemon already running (PID 12345 on 127.0.0.1:4269). Run 'limps stop' first.

This is expected behavior — limps prevents multiple daemons on the same port using PID-based locking.

Resolution:

  • Check all running daemons: limps status-server
  • Stop the existing daemon: limps stop
  • Or start on a different port: limps start --port 8080

Debugging Connection Issues

If MCP clients can't connect to the daemon, verify connectivity step by step:

1. Check daemon status:

limps status-server
# Should show daemon running with healthy status

2. Verify health endpoint:

curl http://127.0.0.1:4269/health
# Should return JSON with status "ok"

3. Verify MCP endpoint:

curl -X POST http://127.0.0.1:4269/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}'
# Should return MCP initialize response

4. Enable debug logging:

DEBUG=1 limps start --foreground
# Watch for connection attempts and errors

5. Check MCP client config:

Ensure the URL in your client config matches the daemon:

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

MCP Tools

limps exposes MCP tools for AI assistants:

CategoryTools
Documentsprocess_doc, process_docs, create_doc, update_doc, delete_doc, list_docs, search_docs, manage_tags, open_document_in_cursor
Planscreate_plan, list_plans, list_agents, get_plan_status
Tasksget_next_task, update_task_status, configure_scoring
Healthcheck_staleness, check_drift, infer_status, get_proposals, apply_proposal
Knowledge Graphgraph (unified: health, search, trace, entity, overlap, reindex, check, suggest)

Knowledge Graph

The knowledge graph builds a structured, queryable representation of your planning documents. It extracts 6 entity types (plan, agent, feature, file, tag, concept) and their relationships (ownership, dependency, modification, tagging, conceptual links). Use it to find conflicts, trace dependencies, and get graph-based suggestions.

# Build the graph from plan files
limps graph reindex

# Check graph health and conflicts
limps graph health --json

# Search entities
limps graph search "auth" --json

# Trace relationships
limps graph trace plan:0042 --direction down

# Detect conflicts (file contention, circular deps, stale WIP)
limps graph check --json

# Get graph-based suggestions
limps graph suggest dependency-order

See Knowledge Graph Architecture and CLI Reference for details.

Health & Automation

limps includes automated health checks that detect issues and suggest fixes:

  • Staleness — Flags plans/agents not updated within configurable thresholds
  • Code drift — Detects when agent frontmatter references files that no longer exist
  • Status inference — Suggests status changes based on dependency completion and body content
  • Proposals — Aggregates all suggestions into reviewable, apply-able fixes
limps health check --json        # Run all checks
limps proposals apply-safe       # Auto-apply safe fixes

Skills & Commands

This repo ships Claude Code slash commands in .claude/commands/ and a Vercel Skills skill in skills/limps-planning.

Claude Code commands (available automatically when limps is your working directory):

CommandDescription
/create-feature-planCreate a full TDD plan with agents
/run-agentPick up and execute the next agent
/close-feature-agentMark an agent PASS and clean up
/update-feature-planRevise an existing plan
/audit-planAudit a plan for completeness
/list-feature-plansList all plans with status
/plan-list-agentsList agents in a plan
/plan-check-statusCheck plan progress
/pr-createCreate a PR from the current branch
/pr-check-and-fixFix CI failures and update PR
/pr-commentsReview and respond to PR comments
/review-branchGeneral code review of current branch
/review-mcpReview code for MCP/LLM safety
/attack-cli-mcpStress-test CLI + MCP for robustness

Vercel Skills (for other AI IDEs):

Install the limps planning skill to get AI-powered guidance for plan creation, agent workflows, and task management:

# Install only the limps planning skill (recommended for consumers)
npx skills add https://github.com/sudosandwich/limps/tree/main/.claude/skills/limps-plan-operations

# Or install all available skills
npx skills add sudosandwich/limps

Available Skills:

SkillDescription
limps-plan-operationsPlan identification, artifact loading, distillation rules, and lifecycle guidance using limps MCP tools
mcp-code-reviewSecurity-focused code review for MCP servers and LLM safety
branch-code-reviewGeneral code review for design, maintainability, and correctness
git-commit-best-practicesConventional commits and repository best practices

See skills.yaml for the complete manifest of the .claude/skills packages installed via npx skills add above; the separate skills/limps-planning/ package in this repo is a legacy distribution and new consumers should prefer the .claude/skills method.

Extensions

Extensions add MCP tools and resources. Install from npm:

npm install -g @sudosandwich/limps-headless

Add to config:

{
  "extensions": ["@sudosandwich/limps-headless"],
  "limps-headless": {
    "cacheDir": "~/Library/Application Support/limps-headless"
  }
}

Available extensions:

  • @sudosandwich/limps-headless — Headless UI contract extraction, semantic analysis, and drift detection (Radix UI and Base UI migration).

Obsidian Compatibility

limps works with Obsidian vaults. Open your plans/ directory as a vault for visual editing:

  • Full YAML frontmatter support
  • Tag management (frontmatter and inline #tag)
  • Automatic exclusion of .obsidian/, .git/, node_modules/

Obsidian vault with limps plans

Development

git clone https://github.com/paulbreuler/limps.git
cd limps
npm install
npm run build
npm test

This is a monorepo with:

  • packages/limps — Core MCP server
  • packages/limps-headless — Headless UI extension (Radix/Base UI contract extraction and audit)

Used in Production

limps manages planning for runi, using a separate folder (in this case a git repo) for plans.

Creating a feature plan

The fastest way is the /create-feature-plan slash command (Claude Code) — it handles numbering, doc creation, and agent distillation automatically via MCP tools. See .claude/commands/create-feature-plan.md for the full spec.

You can also run the same steps manually with MCP tools:

  • list_plans → determine next plan number
  • create_plan → scaffold the plan directory
  • create_doc → add plan, interfaces, README, and agent files
  • update_task_status → track progress

Plans follow this layout:

NNNN-descriptive-name/
├── README.md
├── NNNN-descriptive-name-plan.md
├── interfaces.md
└── agents/
    ├── 000_agent_infrastructure.agent.md
    ├── 001_agent_feature-a.agent.md
    └── ...

Numbered prefixes keep plans and agents lexicographically ordered. get_next_task uses the agent number (plus dependency and workload scores) to suggest what to work on next.

Deep Dive

Plan Structure
plans/
├── 0001-feature-name/
│   ├── 0001-feature-name-plan.md    # Main plan with specs
│   ├── interfaces.md                 # Interface contracts
│   ├── README.md                     # Status index
│   └── agents/                       # Task files
│       ├── 000-setup.md
│       ├── 001-implement.md
│       └── 002-test.md
└── 0002-another-feature/
    └── ...

Agent files use frontmatter to track status:

---
status: GAP | WIP | PASS | BLOCKED
persona: coder | reviewer | pm | customer
depends_on: ["000-setup"]
files:
  - src/components/Feature.tsx
---
Task Scoring Algorithm

get_next_task returns tasks scored by:

ComponentMax PointsDescription
Dependency40All dependencies satisfied = 40, else 0
Priority30Based on agent number (lower = higher priority)
Workload30Based on file count (fewer = higher score)

Biases adjust final scores:

{
  "scoring": {
    "biases": {
      "plans": { "0030-urgent-feature": 20 },
      "personas": { "coder": 5, "reviewer": -10 },
      "statuses": { "GAP": 5, "WIP": -5 }
    }
  }
}
RLM (Recursive Language Model) Support

process_doc and process_docs execute JavaScript in a secure QuickJS sandbox. User-provided code is statically validated and cannot use require, import, eval, fetch, XMLHttpRequest, WebSocket, process, timers, or other host/network APIs—so it cannot make external calls or access the host.

await process_doc({
  path: "plans/0001-feature/plan.md",
  code: `
    const features = extractFeatures(doc.content);
    return features.filter(f => f.status === 'GAP');
  `,
});

Available extractors:

  • extractSections() — Markdown headings
  • extractFrontmatter() — YAML frontmatter
  • extractFeatures() — Plan features with status
  • extractAgents() — Agent metadata
  • extractCodeBlocks() — Fenced code blocks

LLM sub-queries (opt-in):

await process_doc({
  path: "plans/0001/plan.md",
  code: "extractFeatures(doc.content)",
  sub_query: "Summarize each feature",
  allow_llm: true,
  llm_policy: "force", // or 'auto' (skips small results)
});
MCP Resources

Progressive disclosure via resources:

ResourceDescription
plans://indexList of all plans (minimal)
plans://summaryPlan summaries with key info
plans://fullFull plan documents
decisions://logDecision log entries
Example: Custom Cursor Commands

Create .cursor/commands/run-agent.md:

# Run Agent

Start work on the next available task.

## Instructions

1. Use `get_next_task` to find the highest-priority task
2. Use `process_doc` to read the agent file
3. Use `update_task_status` to mark it WIP
4. Follow the agent's instructions

This integrates with limps MCP tools for seamless task management.

What is MCP?

Model Context Protocol is a standardized protocol for AI applications to connect to external systems. Originally from Anthropic (Nov 2024), now part of the Linux Foundation's Agentic AI Foundation.

License

MIT

Keywords

mcp

FAQs

Package last updated on 09 Feb 2026

Related posts