swiss-knife: Instructions file for Claude Code

swiss-knife

Structured-output CLI and MCP toolkit that cuts agent token usage and tool-call count by bundling common operations into deterministic single calls.

Project Overview

• Language: Python 3.13+
• Packaging: uv + hatchling (src layout)
• CLI framework: Click (subcommand groups)
• Entry point: swiss-knife <subcommand>

Architecture

Two layers per tool:

• core.py — pure functions accepting arguments, returning dicts. No I/O, no Click dependency. Fully testable.
• cli.py — thin Click wrapper that calls core functions and writes json.dumps() to stdout via the shared _emit helper.

The MCP server (mcp_server/server.py, served by swiss-knife mcp) wraps the same core functions, so CLI and MCP output match. Shared git subprocess execution lives in _git.py.

Output Contract

All tools write valid JSON to stdout. Exit codes:

• 0 — success
• 1 — outcome-negative but JSON valid: test-summary test failures, wait-for timeout, run-logged non-zero/timed-out command, proc stop survivors
• 2 — unrecoverable error, JSON has {"error": "...", "detail": "..."}

Subcommands

1. file-outline <path> — tree-sitter AST extraction of symbols (functions, classes, methods, types) with signatures and line numbers. No function bodies. Languages: Python, JS/TS, Go, Rust, C.
2. commit-context — bundles git staged diff, recent log, untracked files, and branch info into one JSON blob. Replaces 3-6 tool calls.
3. test-summary <command...> — wraps a test runner, injects structured output flags, parses results into { passed, failed, skipped, failures }. Frameworks: pytest, Jest/Vitest, Go test, cargo test, RSpec, Unity (C).
4. proc find|stop <pattern> — psutil-based (cross-platform) process matching that always excludes the invoking shell chain and any command line containing a swiss-knife invocation (the pkill -f self-match hazard). find reports listening ports and process age; stop signals and confirms per-pid outcomes.
5. wait-for — bounded condition polling (--port, --file, --touched, --gone, --present, --http); every wait has a timeout so it can never loop forever.
6. run-logged [--] <command...> — runs a command with stdout+stderr to a log file (no pipe-buffer blocking, no hidden fatal errors), returns exit code, tail, and optional --grep matches over the full log. Use -- before commands with their own flags.
7. session-brief — bundles git state, .claude/HANDOFF.md, parsed PLAN.md phase statuses, the Claude Code project memory index, the latest pi harness session, and AGENTS.md files for a directory.
8. mcp — serves all of the above as MCP tools over stdio. wait_for_condition/run_logged_command block the single-threaded server up to their timeout; the CLI is preferred for long-running work.