claude-code — parsidion
Building the Project Explorer Agent
parsidion · Claude Code Build Session · 2026-03-16
user ~/Repos/parsidion $ claude
✦ Welcome to Claude Code!
claude-sonnet-4-6 · parsidion
  • A new project-explorer Sonnet agent for deep project analysis
  • Writes Projects/ overview + Patterns/ notes to the vault
  • Makes features searchable cross-project via vault-search
  • Adds agent to install.py and syncs to ~/.claude/
2 files changed Claude Sonnet 9-step workflow vault-first
The Problem: Pattern Reinvention
When working across multiple projects, useful implementation patterns are reinvented from scratch because there's no record of how a prior project solved the same problem. Each session starts with zero cross-project context.
  • Built a layered config system in par-llama — re-invented it 3 months later in another project
  • Wrote a Rich progress CLI — forgot the exact pattern by the next project
  • Solved PTY spoofing in parvault — nothing to reference when it came up again
project-explorer → "explore this project and save it to the vault" Step 1: vault check (no duplicate work) Steps 2-5: deep project analysis Steps 6-7: write overview + pattern notes Step 8: rebuild index (notes are searchable) Future: vault-search "streaming output" → finds the note
The Implementation Plan
user ~/Repos/parsidion $ implement plan: project-explorer agent
Single self-contained agent file, following the same structure as research-agent.md and vault-explorer.md. No new scripts required.
✓Create agents/project-explorer.md — 9-step agent
✓Modify install.py — add to AGENT_SRCS list
Architecture: agent-only approach — reuses existing vault_search.py, update_index.py, and vault-explorer agent. Zero new dependencies.
stdlib-only no new scripts reuses vault infra
Task 1: agents/project-explorer.md
claude → Write agents/project-explorer.md
--- name: project-explorer description: > Use when asked to explore, analyze, or document a project's architecture, features, and patterns for cross-project vault reference. Trigger on: "explore project", "analyze project", "document this project", "save project to vault", "catalog project features", "document project features". Do NOT trigger for general code reading, debugging, or feature implementation — only when the explicit goal is vault documentation of a project. model: sonnet color: green ---
✓ agents/project-explorer.md created (9 steps, 170 lines) ✓ Frontmatter: name ✓ model: sonnet ✓ color: green ✓ ✓ Sonnet chosen — deep analysis needs stronger reasoning than Haiku
Agent: 9-Step Workflow
1Vault Check — semantic search + dispatch vault-explorer; fill gaps only
2Metadata Discovery — README, pyproject.toml, Cargo.toml, Makefile
3Architecture Exploration — Glob + Read, top-level dirs, key modules
4Feature Extraction — 3–8 reusable features, binary --help, Makefile targets
5Pattern Identification — config, error handling, logging, design patterns
6Write Overview Note → Projects/{slug}-overview.md
7Write Pattern Notes → Patterns/{feature-slug}.md (min 3)
8Rebuild Index — update_index.py
9Summary Report — paths created/updated, skipped features, index status
Steps 1–2: Vault Check + Metadata
uv run --no-project ~/.claude/skills/parsidion/scripts/vault_search.py \ "project {name}" -j 2>/dev/null # Also dispatch vault-explorer: "project {name} architecture features" # If notes exist → read, identify gaps, clean up outdated info (update/delete) # If no notes → proceed to full analysis
README.md / README.rst → description, features, usage CLAUDE.md → conventions, architecture notes pyproject.toml → name, version, deps, entry points Cargo.toml / package.json / go.mod Makefile → available commands Extract: project-slug · language+version · frameworks key deps (top 5-10) · entry points · build tool
Steps 3–4: Architecture + Features
# 1. List top-level dirs (one level deep) # 2. Read one representative file per significant dir # 3. Identify main entry point(s) # 4. Note distinctive structural choices: # monorepo · plugin system · layered config · event bus
README feature sections {binary} --help 2>/dev/null || true Key module filenames + light content skim Makefile targets Per feature: what it does · which files · why reusable
3–8 features is the target range — enough to be useful, not so many that the vault fills with noise. Features that are too project-specific are skipped and reported in the summary.
Step 5: Pattern Identification
Beyond individual features, the agent looks for project-level patterns — recurring solutions that appear across many projects and are worth documenting as reusable building blocks.
◆Config handling — YAML, env vars, layered precedence, --config flag
◆Error handling — exceptions, Result types, exit codes, structured errors
◆Logging — Rich, tracing, structured JSON, file-based, debug flags
◆Design patterns — plugin arch, event-driven, strategy, middleware chain
◆Testing approach — unit vs integration, fixtures, mocking conventions
◆CLI conventions — argument parsing, subcommands, output formatting
Patterns identified here drive which Patterns/ notes get written in step 7.
Step 6: Project Overview Note
claude → Write ~/ClaudeVault/Projects/{slug}-overview.md
--- date: YYYY-MM-DD type: project tags: [{name}, {language}, {framework}, project] project: {project-name} confidence: high sources: ["{/absolute/path/to/project}"] related: ["[[{feature-1-slug}]]", "[[{feature-2-slug}]]"] ---
## Summary · ## Tech Stack · ## Architecture ## Features (each links → [[pattern-note]]) ## Key Conventions
CRITICAL: related: [] is never acceptable. The overview's related field must list every pattern note about to be written — even before those notes exist on disk. They become valid wikilinks once step 7 completes.
Step 7: Feature Pattern Notes
claude → Write ~/ClaudeVault/Patterns/{feature-slug}.md
--- date: YYYY-MM-DD type: pattern tags: [{feature-tag}, {project-name}, {language}] project: {project-name} confidence: high sources: ["{/absolute/path/to/implementing/file}"] related: ["[[{project-slug}-overview]]"] ---
## Summary → what it does + why it's reusable ## Implementation → file:line refs + code snippets ## How to Replicate → numbered steps for another project ## Key Learnings → gotchas, trade-offs, insights
Minimum 3 pattern notes. Skip only if: (1) too project-specific to reuse, or (2) a vault note for this exact pattern already exists — add a related link instead.
Steps 8–9: Index + Summary Report
uv run --no-project ~/.claude/skills/parsidion/scripts/update_index.py # Makes all new notes searchable via vault-search immediately # Reports exit code — surfaces errors rather than silently failing
## Project Explorer Summary **Project**: {project-name} **Path**: {/absolute/path} ### Notes Written - ~/ClaudeVault/Projects/{slug}-overview.md — [created|updated] - ~/ClaudeVault/Patterns/{feature-slug}.md — [created|updated] ### Skipped Features - {feature}: {reason skipped} ### Vault Index update_index.py: {success|failed — error message}
Quality Rules
The agent enforces five hard rules to keep the vault healthy. These prevent the most common failure modes found in vault notes: orphan notes, empty sections, and tilde paths that break downstream tools.
1No orphan notes — every related field must contain at least one [[wikilink]]
2No empty sections — omit a heading rather than leaving it blank
3Absolute source paths — sources must use full filesystem path, not ~
4Kebab-case filenames — no date suffix (date goes in frontmatter)
5Search before create — update existing pattern notes; add related link back to overview
Related field format — inline quoted array (per vault convention): related: ["[[note-a]]", "[[note-b]]"] ✓ related: [[[note-a]], [[note-b]]] ✗ (bare) related: ✗ (empty)
Task 2: install.py — AGENT_SRCS
claude → Edit install.py — add project-explorer to AGENT_SRCS
# Before AGENT_SRCS: list[Path] = [ REPO_ROOT / "agents" / "research-agent.md", REPO_ROOT / "agents" / "vault-explorer.md", ]
# After AGENT_SRCS: list[Path] = [ REPO_ROOT / "agents" / "research-agent.md", REPO_ROOT / "agents" / "vault-explorer.md", REPO_ROOT / "agents" / "project-explorer.md", ]
✓ 1 line added — the AGENT_SRCS list pattern from the vault-explorer session already makes install.py scale to N agents with no further changes.
1 line change AGENT_SRCS list no other sites needed
Verification: Dry-run + Install
$ uv run install.py --dry-run --yes Installation Plan Install agent: ~/.claude/agents/research-agent.md Install agent: ~/.claude/agents/vault-explorer.md Install agent: ~/.claude/agents/project-explorer.md [dry-run] Install agent: research-agent.md → ~/.claude/agents/ [dry-run] Install agent: vault-explorer.md → ~/.claude/agents/ [dry-run] Install agent: project-explorer.md → ~/.claude/agents/ ✓ Dry run complete — no changes were made.
$ uv run install.py --force --yes + Install agent: project-explorer.md → ~/.claude/agents/ ✓ Vault index rebuilt ✓ Installation complete! $ ls -la ~/.claude/agents/project-explorer.md -rw-r--r-- 1 probello staff 7028 Mar 15 22:59 ~/.claude/agents/project-explorer.md ✓
Using the Agent
user ~/Repos/par-llama $ explore this project and save it to the vault
Dispatching project-explorer agent to analyze par-llama and save structured notes to the vault.
~/ClaudeVault/Projects/par-llama-overview.md → created ~/ClaudeVault/Patterns/streaming-llm-output.md → created ~/ClaudeVault/Patterns/model-provider-abstraction.md → created ~/ClaudeVault/Patterns/rich-progress-cli.md → created update_index.py: success
$ vault-search "streaming output" -n 5 → ~/ClaudeVault/Patterns/streaming-llm-output.md score: 0.91 (Implementation in par-llama: src/streaming.py:42)
What We Built
  • agents/project-explorer.md — Sonnet agent
  • ~/.claude/agents/project-explorer.md
  • install.py — 1 line to AGENT_SRCS
  • Uses Sonnet (not Haiku) — deep reasoning needed for architecture analysis
  • vault-first — checks for existing notes before writing anything; updates, not duplicates
  • Dispatches vault-explorer as a sub-step — reuses proven search logic
  • Minimum 3 pattern notes enforced — ensures useful vault output every time
  • Bidirectional links — overview ↔ pattern notes via wikilinks
  • update_index.py always last — notes immediately searchable via vault-search
Live in ~/.claude/ Sonnet model 9-step workflow vault-first cross-project search