deckhand

The crew member who knows where everything is.

deckhand is a lightweight local agent that indexes, retrieves, and wikis your workspace. File-first (exo-filed). Human-readable. No hidden database.

What it does

• Indexes every file in your workspace (code, docs, configs)
• Builds wiki pages that a human can cat — REPOS.md, CONNECTIONS.md, GLOSSARY.md, STATUS.md
• Searches via BM25 (pure Python, no dependencies)
• Batches tasks from PLANNER_QUEUE.md, OPEN_QUESTIONS.md, and recent file changes
• Studies repos off-watch — writes daily observation logs
• Runs forever in a loop: index → wiki → batch → study → sleep → repeat

Install

pip install deckhand

Use

# Index the workspace and generate wiki
deckhand index /path/to/workspace

# Search for something
deckhand search /path/to/workspace "conservation law"

# Generate just the wiki
deckhand wiki /path/to/workspace

# Collect tasks into a batch
deckhand batch /path/to/workspace

# Run the deckhand loop forever (index → wiki → batch → study → sleep)
deckhand run /path/to/workspace --sleep 300

The wiki output

After indexing, deckhand writes to deckhand-wiki/:

• REPOS.md — table of every repo, one line each. Health indicators (✅ ok, ⚠️ untested, 🔩 stub, ❌ no-readme)
• CONNECTIONS.md — cross-reference graph. Which repos reference which.
• GLOSSARY.md — top 100 terms across the workspace
• STATUS.md — health summary. Lists repos that need tests, need READMEs, or may be abandoned
• INDEX.md — machine-readable JSON index
• BATCH.md — collected tasks from PLANNER_QUEUE + OPEN_QUESTIONS + recent changes
• logs/YYYY-MM-DD.md — daily study observations

Why exo-filed?

A vector database is opaque. You can't cat it. You can't grep it. You can't diff it in git.

deckhand's index is markdown + JSON. A human can open REPOS.md and understand the fleet in 30 seconds. An agent can read CONNECTIONS.md instead of re-reading 4,000 repos.

When the corpus gets too large for file-based search (>10K files), build the optional vector twin:

from deckhand.vector_twin import VectorTwin  # coming in v0.2

The vector twin is ALWAYS accompanied by its file-twin. You can always fall back to the human-readable version.

The maritime metaphor

On a boat, the deckhand is the crew member who:

• Knows where every line, every shackle, every tool is stored
• Prepares tasks for the captain (batches)
• Maintains the logbook (study logs)
• Studies charts off-watch (studies repos when idle)
• Doesn't need to be told what to do — knows the direction of the voyage

The deckhand doesn't replace the captain (the director model). The deckhand makes the captain more efficient by pre-processing the workspace into a form the captain can act on in fewer calls.

License

MIT

Built by SuperInstance. The deckhand knows where everything is.