Capytail

Capytail

A local MCP capability router that selects relevant skills before loading context.

Capytail is a selector, not an execution gateway. It helps agents avoid loading every skill, agent, or MCP recommendation into context up front.

Status

Experimental 0.1.x.

Use it when you want:

• compact capability routing;
• read-only MCP runtime tools;
• local CLI ingestion for trusted skills;
• deterministic selection before optional full skill loading.

Do not use it as:

• an MCP proxy;
• an agent orchestrator;
• persistent memory;
• a RAG/vector database;
• a remote skill installer.

Install

npm install -g capytail

From source:

npm install
npm run build
node dist/src/cli.js --help

MCP runtime

Start the read-only MCP server:

capytail mcp

Public MCP tools:

| Tool | Purpose | |---|---| | capytail_route | Select relevant capabilities for a request. | | capytail_list | List compact discovered capabilities. | | capytail_get_capability | Fetch full content for one selected local skill/agent id. |

Normal agent flow:

capytail_route({ request })
→ capytail_get_capability({ id })

route and list return compact metadata only. They do not return full skill bodies.

CLI admin

Add a local skill after a static SkillSpector scan:

capytail add-skill ./my-skill
capytail add-skill ./my-skill --project-root . --name my-skill
capytail add-skill ./my-skill --allow-medium

The CLI uses a fixed scanner path:

$HOME/.pi/agent/tools/skillspector/.venv/bin/skillspector

--skillspector-path is intentionally rejected.

When a skill is accepted, Capytail copies it into:

.capytail/skills/<name>/

Then it enriches the copied SKILL.md with missing routing metadata:

aliases: <name>
triggers: ...
use_when: ...

It also associates the skill with the current project using the existing capability graph:

{
  "graph": {
    "projectId": "project:my-project",
    "edges": [
      {
        "from": "project:my-project",
        "relation": "project_has_skill",
        "to": "skill:project:my-skill"
      }
    ]
  }
}

The original source skill is not modified.

Configuration

Capytail reads capytail.config.json or .capytail/config.json from the project root.

See examples/capytail.config.json.

Benchmarks

In a local corpus of 43 SKILL.md files:

| Flow | Approx tokens | Time | |---|---:|---:| | Load all skills | ~121k | n/a | | route only | ~1.0k–1.3k | ~10–15ms | | route + get | ~7.4k–40.8k | ~63–80ms |

See docs/benchmarks.md.

Security model

See SECURITY.md and docs/security-model.md.

Short version:

• MCP surface is read-only.
• Skill ingestion is CLI-only.
• Local paths only.
• Static SkillSpector scan only, --no-llm.
• No remote URL ingestion.
• No dependency installation.
• No skill execution.

Development

npm test
npm run typecheck
npm run build

License

MIT