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
What we're building
- 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.
Common scenarios
- 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
The fix
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.
Files
✓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
Frontmatter
---
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
Step 1 — vault check before writing anything
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
Step 2 — files read for metadata extraction
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
Step 3 — architecture exploration
# 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
Step 4 — feature extraction sources
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.
Pattern categories
◆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
Frontmatter
---
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}]]"]
---
Body sections
## 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
Frontmatter
---
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]]"]
---
Body sections
## 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
Step 8 — rebuild vault index
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
Step 9 — structured summary report
## 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
Change
# 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
Dry-run confirms new agent in plan
$ 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.
Live install
$ 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
Invoke from any project directory
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.
Expected output
~/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
Cross-project search after exploration
$ 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
New files
- agents/project-explorer.md — Sonnet agent
- ~/.claude/agents/project-explorer.md
Modified files
- install.py — 1 line to AGENT_SRCS
Key design decisions
- 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