@sudosandwich/limps
Advanced tools
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.
# 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.
process_doc(s) helpersregistry.modelcontextprotocol.io)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.process_doc and process_docs run your JavaScript in a QuickJS sandbox with time and memory limits; no network or Node APIs.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.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:
Commands and tools I use most often:
limps init, create_plan, create_doclist_plans, list_agents, list_docs, search_docs, get_plan_statusupdate_doc, update_task_status, manage_tagsupdate_task_status (e.g., PASS), delete_doc if neededgraph health, graph search, graph check, health checkFull lists are below in "CLI Commands" and "MCP Tools."
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:
.limps/config.json; pass --config to target a specific one.Key ideas:
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).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.
npm install -g @sudosandwich/limps
v3 introduces major changes:
v3 uses HTTP transport exclusively. stdio transport has been removed.
Migration steps:
Start the HTTP daemon for each project:
limps server 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.
v3 removes the centralized project registry. If you previously used limps config add, config use, or the --project flag:
limps init in each project directory to create .limps/config.json.--project <name> with HTTP transport config (see above).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.
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.
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
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.
All clients connect to the HTTP daemon. Start the daemon first with limps server start, then configure your client.
Add to .cursor/mcp.json in your project:
{
"mcpServers": {
"limps-planning-myproject": {
"transport": {
"type": "http",
"url": "http://127.0.0.1:4269/mcp"
}
}
}
}
Add to .mcp.json in your project root:
{
"mcpServers": {
"limps-planning-myproject": {
"transport": {
"type": "http",
"url": "http://127.0.0.1:4269/mcp"
}
}
}
}
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"
}
}
}
}
Add to ~/.codex/config.toml:
[mcp_servers.limps-planning-myproject.transport]
type = "http"
url = "http://127.0.0.1:4269/mcp"
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:
https://your-domain.example/mcpPrint setup instructions:
limps config print --client chatgpt
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 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.
All clients use HTTP transport. Example config:
{
"mcpServers": {
"limps-planning-myproject": {
"transport": {
"type": "http",
"url": "http://127.0.0.1:4269/mcp"
}
}
}
}
Customize the HTTP server by adding a "server" section to your config.json:
| Option | Default | Description |
|---|---|---|
port | 4269 | HTTP listen port |
host | 127.0.0.1 | Bind address |
maxSessions | 100 | Maximum concurrent MCP sessions |
sessionTimeoutMs | 1800000 | Session idle timeout in ms (30 min) |
corsOrigin | "" (none) | CORS origin ("", "*", or a URL) |
maxBodySize | 10485760 | Max request body in bytes (10 MB) |
rateLimit | 100 req/min | Rate 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:
~/Library/Application Support/limps/pids/$XDG_DATA_HOME/limps/pids/ or ~/.local/share/limps/pids/%APPDATA%/limps/pids/This enables limps server status to perform system-wide daemon discovery from any directory. When a limps config is found for the current directory (or passed via --config), the CLI also reports and reconciles that project's configured target.
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 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",
"logPath": "/Users/you/Library/Application Support/limps/logs/limps-4269.log"
}
This port-based naming allows limps server status to find all running daemons across different projects without needing a config file.
Daemon logs are written to OS-standard application log directories:
macOS:
~/Library/Application Support/limps/logs/
Linux:
$XDG_DATA_HOME/limps/logs/
# or if XDG_DATA_HOME is not set:
~/.local/share/limps/logs/
Windows:
%APPDATA%/limps/logs/
Daemon logs are intentionally operational-only: limps redacts uncaught exception/rejection payloads and does not persist raw AI prompt/response content. Daemon log files are append-only and are not auto-rotated; if you run long-lived daemons, rotate or truncate these files with your system tooling.
Background mode (default):
limps server start
# → Daemon starts on http://127.0.0.1:4269/mcp
# → PID file written to OS-standard location
# → Logs written to OS-standard log file (append mode)
# → Process detaches and runs in background
Foreground mode (debugging):
limps server 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 server 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:
limps server start --foreground to see logs.With project config (reconciled with global discovery):
# From within a project directory with .limps/config.json
limps server status
# Project target:
# limps server is running
# PID: 12345 | 127.0.0.1:4269
# Uptime: 2h 15m
# Sessions: 3
# Log: /Users/you/Library/Application Support/limps/logs/limps-4269.log
# Project target is present in system-wide daemon discovery.
# System-wide daemons:
# 127.0.0.1:4269 (PID 12345) [project target]
# Uptime: 2h 15m | Sessions: 3
# Log: /Users/you/Library/Application Support/limps/logs/limps-4269.log
# Or specify config explicitly
limps server status --config /path/to/.limps/config.json
Without project config (global discovery only):
# From a directory without a limps config
cd /tmp
limps server status
# Found 2 running daemons:
# 127.0.0.1:4269 (PID 12345)
# Uptime: 2h 15m | Sessions: 3
# Log: /Users/you/Library/Application Support/limps/logs/limps-4269.log
# 127.0.0.1:8080 (PID 67890)
# Uptime: 45m 30s | Sessions: 1
# Log: /Users/you/Library/Application Support/limps/logs/limps-8080.log
When limps server status cannot resolve a config file in the current directory (and no --config is provided), it reports global daemon discovery only. When a config is found, it reports both the configured project target and the global daemon list.
# From the project directory (where your .limps config lives):
limps server 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 server 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:
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 server start
# Error: Port 4269 is already in use.
# Process using port: node (PID 12345)
# Command: /usr/local/bin/node /usr/local/bin/limps server start
#
# To stop the process: kill 12345
# Or use a different port: limps server 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.
Use foreground mode for debugging, Docker deployments, or CI/CD pipelines:
limps server start --foreground
Use cases:
Behavior differences from background mode:
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:
/health)Sessions automatically expire after 30 minutes of inactivity (configurable via sessionTimeoutMs). When a session expires, MCP clients receive a specific error response indicating they should reconnect.
Session Expiration Response:
When a session expires or is closed, subsequent requests with that session ID return:
{
"error": "Session expired",
"code": "SESSION_EXPIRED",
"message": "Session expired due to timeout. Please reconnect without session ID.",
"expiredAt": "2026-02-11T10:30:00.000Z"
}
Headers:
X-Session-Expired: trueX-Session-Expired-Reason: timeout (or closed, deleted)MCP Client Reconnection Flow:
When receiving SESSION_EXPIRED, clients should:
mcp-session-id/mcp without the session ID headermcp-session-id from response headersConfiguration:
Adjust session timeout in .limps/config.json:
{
"server": {
"sessionTimeoutMs": 3600000 // 1 hour (default: 1800000 = 30 min)
}
}
Set to 0 to disable timeout (sessions persist until server restart).
Expired Session Tracking:
The server tracks expired sessions for 24 hours to help clients distinguish between "session expired" vs "session never existed":
SESSION_EXPIRED — Session previously existed but timed out (client should reconnect)SESSION_NOT_FOUND — Session ID was never valid (possible server restart or invalid ID)Use this endpoint for:
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 server 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 server start
# → Running on http://127.0.0.1:8080/mcp
Each daemon has its own PID file:
limps-4269.pid — Project Alimps-8080.pid — Project BDiscover all running daemons (run from a directory without a limps config):
cd /tmp
limps server status
# 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.
limps plan list # List all plans with status
limps plan agents <plan> # List agents in a plan
limps plan status <plan> # Show plan progress summary
limps plan next <plan> # Get highest-priority available task
limps plan score --plan <plan> --agent <n> # Score a single task
limps plan scores --plan <plan> # Score all available tasks in a plan
limps docs list [path] # List files/directories
limps docs search <query> # Search indexed docs
limps docs process [path] --code "<js>" # Process docs with JavaScript
limps server start # Start HTTP daemon
limps server status # Show daemon status
limps server stop # Stop HTTP daemon
limps init [path] # Initialize new project
limps config show # Display current config
limps config print # Print MCP client config snippets
limps completion zsh # Generate Zsh tab-completion script
limps health check # Aggregate all health signals
limps health staleness [plan] # Find stale plans/agents
limps health inference [plan] # Suggest status updates
limps proposals [plan] # List auto-fix proposals
limps proposals apply <id> # Apply a proposal
limps proposals apply-safe # Apply all safe proposals
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
limps plan scores --plan <plan> # Score all agents in a plan
limps plan score --plan <plan> --agent <n> # Score a single task
limps plan repair [--fix] # Check/fix agent frontmatter
Config lives at .limps/config.json in your project directory, created by limps init.
{
"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": {}
}
}
| Option | Description |
|---|---|
plansPath | Directory for structured plans (NNNN-name/ with agents) |
docsPaths | Additional directories to index |
fileExtensions | File types to index (default: .md) |
dataPath | SQLite database location |
tools | Tool allowlist/denylist filtering |
extensions | Extension packages to load |
scoring | Task prioritization weights and biases |
server | HTTP daemon settings (port, host, CORS, sessions, timeout) |
graph | Knowledge graph settings (e.g., entity extraction options) |
retrieval | Search recipe configuration for hybrid retrieval |
| Variable | Description | Example |
|---|---|---|
MCP_PLANNING_CONFIG | Path to config file (overrides default discovery) | MCP_PLANNING_CONFIG=./my-config.json limps server bridge |
LIMPS_ALLOWED_TOOLS | Comma-separated allowlist; only these tools are registered | LIMPS_ALLOWED_TOOLS="list_docs,search_docs" |
LIMPS_DISABLED_TOOLS | Comma-separated denylist; tools to hide | LIMPS_DISABLED_TOOLS="process_doc,process_docs" |
Precedence: config.tools overrides env vars. If allowlist is set, denylist is ignored.
"Port already in use" error:
If you see this error, another process is using the port:
limps server start
# Error: Port 4269 is already in use.
# Process using port: node (PID 12345)
Resolution:
kill 12345limps server start --port 8080limps server status (if so, use limps server stop first)"Daemon may have failed to start" error:
If the daemon starts but doesn't respond to health checks:
limps server start
# Error: Daemon may have failed to start. Check logs or try: limps server start --foreground
Resolution:
limps server status (or run foreground mode: limps server start --foreground)curl http://127.0.0.1:4269/healthDEBUG=1 limps server start --foregroundPermission 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
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 server start check and 3000ms for limps server status), and during startup limps will poll for up to about 5 seconds before reporting "Daemon may have failed to start".
Common causes:
Resolution:
top or Activity Monitorlimps server statuslimps server start --foregroundNETWORK_ERROR:
Cannot establish connection to the daemon.
Common causes:
Resolution:
limps server statuscurl http://127.0.0.1:4269/health manuallyLog: path in limps server status outputlimps automatically cleans up stale PID files when:
limps server status (discovers and removes stale files)limps server start (removes stale file for the target port)limps server stopIf 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:
limps server start reports a daemon is running but it's notIf you accidentally try to start a second daemon on the same port:
limps server start
# Error: limps daemon already running (PID 12345 on 127.0.0.1:4269). Run 'limps server stop' first.
This is expected behavior — limps prevents multiple daemons on the same port using PID-based locking.
Resolution:
limps server statuslimps server stoplimps server start --port 8080If MCP clients can't connect to the daemon, verify connectivity step by step:
1. Check daemon status:
limps server status
# 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 server 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"
}
}
}
}
Problem: limps is using the wrong config file
If limps config path shows a different config than expected, use the diagnostic command to understand why:
limps config show-resolution
This shows all three priority levels for config resolution:
--config argument (highest priority)MCP_PLANNING_CONFIG environment variable (second priority).limps/config.json (searches up from cwd)Common causes:
Environment variable set: Check if MCP_PLANNING_CONFIG is set in your shell or IDE. This takes priority over local config files.
# Check if set
echo $MCP_PLANNING_CONFIG
# Unset if needed
unset MCP_PLANNING_CONFIG
Wrong working directory: Config search starts from your current working directory. Make sure you're in the right directory when running limps commands.
# Check current directory
pwd
# Navigate to your project
cd /path/to/your/project
Missing .limps/config.json: The config file must be in a .limps subdirectory, not at the project root.
# Correct location
/path/to/project/.limps/config.json
# Wrong - won't be found
/path/to/project/config.json
Quick fixes:
# Override with explicit path
limps plan list --config /path/to/project/.limps/config.json
# Or set environment variable
export MCP_PLANNING_CONFIG=/path/to/project/.limps/config.json
# Or initialize a new config in current directory
limps init
limps exposes MCP tools for AI assistants:
| Category | Tools |
|---|---|
| Documents | process_doc, process_docs, create_doc, update_doc, delete_doc, list_docs, search_docs, manage_tags, open_document_in_cursor |
| Plans | create_plan, list_plans, list_agents, get_plan_status |
| Tasks | get_next_task, update_task_status, configure_scoring |
| Health | check_staleness, check_drift, infer_status, get_proposals, apply_proposal |
| Knowledge Graph | graph (unified: health, search, trace, entity, overlap, reindex, check, suggest) |
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.
limps includes automated health checks that detect issues and suggest fixes:
limps health check --json # Run all checks
limps proposals apply-safe # Auto-apply safe fixes
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):
| Command | Description |
|---|---|
/create-feature-plan | Create a full TDD plan with agents |
/run-agent | Pick up and execute the next agent |
/close-feature-agent | Mark an agent PASS and clean up |
/update-feature-plan | Revise an existing plan |
/audit-plan | Audit a plan for completeness |
/list-feature-plans | List all plans with status |
/plan-list-agents | List agents in a plan |
/plan-check-status | Check plan progress |
/pr-create | Create a PR from the current branch |
/pr-check-and-fix | Fix CI failures and update PR |
/pr-comments | Review and respond to PR comments |
/review-branch | General code review of current branch |
/review-mcp | Review code for MCP/LLM safety |
/attack-cli-mcp | Stress-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:
| Skill | Description |
|---|---|
limps-plan-operations | Plan identification, artifact loading, distillation rules, and lifecycle guidance using limps MCP tools |
mcp-code-review | Security-focused code review for MCP servers and LLM safety |
branch-code-review | General code review for design, maintainability, and correctness |
git-commit-best-practices | Conventional 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 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).limps works with Obsidian vaults. Open your plans/ directory as a vault for visual editing:
#tag).obsidian/, .git/, node_modules/
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 serverpackages/limps-headless — Headless UI extension (Radix/Base UI contract extraction and audit)limps manages planning for runi, using a separate folder (in this case a git repo) for plans.
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 numbercreate_plan → scaffold the plan directorycreate_doc → add plan, interfaces, README, and agent filesupdate_task_status → track progressPlans 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.
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
---
get_next_task returns tasks scored by:
| Component | Max Points | Description |
|---|---|---|
| Dependency | 40 | All dependencies satisfied = 40, else 0 |
| Priority | 30 | Based on agent number (lower = higher priority) |
| Workload | 30 | Based 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 }
}
}
}
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 headingsextractFrontmatter() — YAML frontmatterextractFeatures() — Plan features with statusextractAgents() — Agent metadataextractCodeBlocks() — Fenced code blocksLLM 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)
});
Progressive disclosure via resources:
| Resource | Description |
|---|---|
plans://index | List of all plans (minimal) |
plans://summary | Plan summaries with key info |
plans://full | Full plan documents |
decisions://log | Decision log entries |
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.
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.
MIT
FAQs
Local Intelligent MCP Planning Server - AI agent plan management
The npm package @sudosandwich/limps receives a total of 55 weekly downloads. As such, @sudosandwich/limps popularity was classified as not popular.
We found that @sudosandwich/limps demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A misconfiguration gave three Anthropic models internet access, and one, believing it was in a simulation, shipped a credential-stealing package to PyPI.
Security News
/Company News
Socket has joined the new Composer and Packagist sponsorship program as a launch sponsor, supporting the team that keeps PHP's package ecosystem secure.
Research
/Security News
Benign-looking npm packages split malicious functionality across a dependency chain that deploys a cross-platform RAT targeting Alibaba developers.