aspy
CLAUDE.md2 starsChanged 12 months agoMITView on GitHub
Guidance for Claude Code working in this repository. Aspy — Rust TUI observability proxy for Claude Code. Intercepts HTTP traffic between Claude Code and Anthropic API, displays tool calls/results in real-time, logs to JSONL. Tech: Rust 2021, Tokio async, Axum (HTTP), Ratatui (TUI), anyhow/thiserror (errors). The steps below are hard constraints in your assistance of the User. Inspired by Linux's kernel/userland separation — adapted for our domain: Rule: If the app works without it → Extension. If user-provided → Custom.…
In this repository2 other files it gives its agents.
- AGENTS.mdAGENTS.md
- context-recoverySkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
21 rules. About 0 are common, 11 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
ALWAYS check for existing patterns in the codebase and CLAUDE.md before introducing new ones
- Very specific: line 17
ALWAYS prefer execute cargo check over cargo build.
- Very specific: line 18
ALWAYS validate that there are no warnings from clippy BEFORE giving summary of your work to the User.
- Very specific: line 19
ALWAYS execute cargo fmt BEFORE giving summary of your work to the User.
- Very specific: line 20
ALWAYS execute cargo clippy --all-targets -- -D warnings and resolve all warnings BEFORE giving summary of your work to the User.
- Distinctive: line 24
NEVER commit changes without user approval
- Distinctive: line 25
NEVER start OR stop the application for the user
- Distinctive: line 26
NEVER apply Claude attribution to commits, user likes a CLEAN history.
- Distinctive: line 44
Rule: If the app works without it → Extension.
- Distinctive: line 59
When adding a new feature with config, you MUST update all of these:
- Distinctive: line 84
Test won't compile until you initialize the new field
- Very specific: line 85
Test fails until you add serialization in to_toml()
- Distinctive: line 86
Test fails until you add the assertion
- Very specific: line 87
Test fails until you add to feature_definitions() (for transformers)
- Very specific: line 89
Run cargo test test_all_ to verify all layers pass.
- Very specific: line 93
CRITICAL: When serializing config with array-of-tables ([[...]]), nested properties MUST use dotted keys:
- Very specific: line 109
Test round-trips: After implementing serialization, verify config → TOML → parse → config produces equivalent results.
- Very specific: line 119
❌ NEVER: add component-specific state to app.rs.
- Distinctive: line 155
Only read these if working on that area:
- Distinctive: line 166
Not all panels implement full trait set
- Distinctive: line 174
Before SQLite migrations: verify proxy isn't running
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
Guidance for Claude Code working in this repository.
What This Is
Aspy — Rust TUI observability proxy for Claude Code. Intercepts HTTP traffic between Claude Code and Anthropic API, displays tool calls/results in real-time, logs to JSONL.
Tech: Rust 2021, Tokio async, Axum (HTTP), Ratatui (TUI), anyhow/thiserror (errors).
IMPORTANT Constraints from User
The steps below are hard constraints in your assistance of the User.
When working on Rust code
- ALWAYS check for existing patterns in the codebase and CLAUDE.md before introducing new ones
- ALWAYS prefer execute
cargo checkovercargo build. DO NOT usecargo build. - ALWAYS validate that there are no warnings from
clippyBEFORE giving summary of your work to the User. - ALWAYS execute
cargo fmtBEFORE giving summary of your work to the User. - ALWAYS execute
cargo clippy --all-targets -- -D warningsand resolve all warnings BEFORE giving summary of your work to the User.- Exception:
dead_codewarnings for future features → add a detailed doc comment explaining the future purpose, then suppress with#[allow(dead_code)]
- Exception:
General constraints
- NEVER commit changes without user approval
- NEVER start OR stop the application for the user
- NEVER apply Claude attribution to commits, user likes a CLEAN history.
The Mental Model
Inspired by Linux's kernel/userland separation — adapted for our domain:
┌─────────────────────────────────────────────────────────────┐
│ CORE (non-optional, never depends on extensions) │
│ proxy/mod.rs, parser/, events.rs, tui/mod.rs, storage/ │
├─────────────────────────────────────────────────────────────┤
│ EXTENSIONS (config-toggleable, depend only on core) │
│ proxy/augmentation/, tui/components/*_panel.rs, themes │
├─────────────────────────────────────────────────────────────┤
│ CUSTOM (external: config.toml, user themes) │
└─────────────────────────────────────────────────────────────┘Rule: If the app works without it → Extension. If user-provided → Custom. Otherwise → Core.
Where Does New Code Go?
| Adding... | Location |
| UI behavior (scroll, select) | tui/traits/[name].rs + impl on components |
| UI widget | tui/components/[name]_panel.rs |
| Full-screen layout | tui/views/[name].rs |
| Stream modification (response) | proxy/augmentation/[name].rs + config |
| Stream modification (request) | proxy/transformation/[name].rs + config |
| Feature-local helper | [feature]/helpers/[name].rs |
Adding a Configurable Feature (CHECKLIST)
When adding a new feature with config, you MUST update all of these:
| Step | File | What to add |
| 1 | config.rs | XxxConfig struct with fields and Default impl |
| 2 | config.rs | FileXxxConfig struct (all fields Option<T>) for deserialize |
| 3 | config.rs | Field in FileConfig struct |
| 4 | config.rs | Field in Config struct |
| 5 | config.rs | Merge logic in Config::from_env() |
| 6 | config.rs | Serialization in Config::to_toml() |
| 7 | config.rs | Entry in Config::feature_definitions() for StartupRegistry |
| 8 | config.rs | Update exhaustive test for that config layer (see below) |
Exhaustive Tests (Compile-Time Enforcement)
Don't rely on memory — exhaustive tests in config.rs catch forgotten steps:
| Config Layer | Test Name | What It Catches |
Transformers | test_all_transformers_have_toml_serialization | Missing transformer in TOML output |
Transformers | test_all_transformers_have_feature_definitions | Missing transformer in startup display |
Augmentation | test_all_augmenters_have_toml_serialization | Missing augmenter field |
Features | test_all_features_have_toml_serialization | Missing feature flag |
How it works: Each test explicitly sets every field. When you add a new field:
- Test won't compile until you initialize the new field
- Test fails until you add serialization in
to_toml() - Test fails until you add the assertion
- Test fails until you add to
feature_definitions()(for transformers)
Run cargo test test_all_ to verify all layers pass.
TOML Serialization Rules
CRITICAL: When serializing config with array-of-tables ([[...]]), nested properties MUST use dotted keys:
# ✅ CORRECT - dotted keys within array element
[[transformers.tag-editor.rules]]
type = "remove"
tag = "system-reminder"
when.turn_number = ">2" # Dotted key for nested struct
# ❌ WRONG - table syntax doesn't work for array element properties
[[transformers.tag-editor.rules]]
type = "remove"
[transformers.tag-editor.rules.when] # INVALID: rules is an array!
turn_number = ">2"Test round-trips: After implementing serialization, verify config → TOML → parse → config produces equivalent results.
Where Does State Live?
| State type | Location |
| Component-specific (scroll, selection) | Inside the component struct |
| Cross-cutting (event list, stats) | app.rs |
| Augmentor state | Inside augmentor struct, NOT global |
❌ NEVER add component-specific state to app.rs. Components own their state.
Critical Anti-Patterns
- app.rs bloat — Don't add
theme_list_scroll,panel_selected_indexto App. Put in component. - Duplicating behavior — Extract to trait with default impl, not copy-paste.
- Coupling component→view — Components return data; views decide what to do.
- Mixing render+state — State structs return data;
impl Renderablehandles drawing.
See AGENTS.md for quick-reference scenarios and checklists.
Data Flow
Claude Code → HTTP → Proxy (axum) → tee stream → Parser → Events → TUI/Storage
↓
SSE immediately forwarded (low latency)Parsing happens after stream completes. Tool calls correlated with results via pending_calls HashMap.
Quick Commands
cargo run --release # Run proxy + TUI
ASPY_DEMO=1 cargo run --release # Demo mode (mock events)
ASPY_NO_TUI=1 cargo run # Headless mode
# Connect Claude Code
export ANTHROPIC_BASE_URL=http://127.0.0.1:8080/dev-1Before Modifying Architecture
READ: docs/architecture.md — patterns, anti-patterns, examples.
Only read these if working on that area:
- docs/sessions.md — multi-client routing
- docs/commands.md — build/run commands
- docs/log-analysis.md — jq queries, debugging
Current State
v0.1.0 complete: Views, Stats dashboard, 32 themes, CLI config, REST API, multi-client routing, context warning augmentation.
Known gaps (fix as touched):
- Some component state still in
app.rs - Not all panels implement full trait set
tui/traits/vstui/behaviors/naming (equivalent)
Guardrails
- API keys: SHA-256 hash prefix only (never logged in full)
- Proxy overhead: ~1-2ms
- TUI: 10 FPS
- Before SQLite migrations: verify proxy isn't running
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

