agentleFS
omgpointlessomgpointless/aspy/CLAUDE.md

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.…

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
  1. Distinctive:

    ALWAYS check for existing patterns in the codebase and CLAUDE.md before introducing new ones

    line 16
  2. Very specific:

    ALWAYS prefer execute cargo check over cargo build.

    line 17
  3. Very specific:

    ALWAYS validate that there are no warnings from clippy BEFORE giving summary of your work to the User.

    line 18
  4. Very specific:

    ALWAYS execute cargo fmt BEFORE giving summary of your work to the User.

    line 19
  5. Very specific:

    ALWAYS execute cargo clippy --all-targets -- -D warnings and resolve all warnings BEFORE giving summary of your work to the User.

    line 20
  6. Distinctive:

    NEVER commit changes without user approval

    line 24
  7. Distinctive:

    NEVER start OR stop the application for the user

    line 25
  8. Distinctive:

    NEVER apply Claude attribution to commits, user likes a CLEAN history.

    line 26
  9. Distinctive:

    Rule: If the app works without it → Extension.

    line 44
  10. Distinctive:

    When adding a new feature with config, you MUST update all of these:

    line 59
  11. Distinctive:

    Test won't compile until you initialize the new field

    line 84
  12. Very specific:

    Test fails until you add serialization in to_toml()

    line 85
  13. Distinctive:

    Test fails until you add the assertion

    line 86
  14. Very specific:

    Test fails until you add to feature_definitions() (for transformers)

    line 87
  15. Very specific:

    Run cargo test test_all_ to verify all layers pass.

    line 89
  16. Very specific:

    CRITICAL: When serializing config with array-of-tables ([[...]]), nested properties MUST use dotted keys:

    line 93
  17. Very specific:

    Test round-trips: After implementing serialization, verify config → TOML → parse → config produces equivalent results.

    line 109
  18. Very specific:

    ❌ NEVER: add component-specific state to app.rs.

    line 119
  19. Distinctive:

    Only read these if working on that area:

    line 155
  20. Distinctive:

    Not all panels implement full trait set

    line 166
  21. Distinctive:

    Before SQLite migrations: verify proxy isn't running

    line 174

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 check over cargo build. DO NOT use cargo build.
  • ALWAYS validate that there are no warnings from clippy BEFORE giving summary of your work to the User.
  • ALWAYS execute cargo fmt BEFORE giving summary of your work to the User.
  • ALWAYS execute cargo clippy --all-targets -- -D warnings and resolve all warnings BEFORE giving summary of your work to the User.
    • Exception: dead_code warnings for future features → add a detailed doc comment explaining the future purpose, then suppress with #[allow(dead_code)]

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 widgettui/components/[name]_panel.rs
Full-screen layouttui/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:

StepFileWhat to add
1config.rsXxxConfig struct with fields and Default impl
2config.rsFileXxxConfig struct (all fields Option<T>) for deserialize
3config.rsField in FileConfig struct
4config.rsField in Config struct
5config.rsMerge logic in Config::from_env()
6config.rsSerialization in Config::to_toml()
7config.rsEntry in Config::feature_definitions() for StartupRegistry
8config.rsUpdate 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 LayerTest NameWhat It Catches
Transformerstest_all_transformers_have_toml_serializationMissing transformer in TOML output
Transformerstest_all_transformers_have_feature_definitionsMissing transformer in startup display
Augmentationtest_all_augmenters_have_toml_serializationMissing augmenter field
Featurestest_all_features_have_toml_serializationMissing feature flag

How it works: Each test explicitly sets every field. When you add a new field:

  1. Test won't compile until you initialize the new field
  2. Test fails until you add serialization in to_toml()
  3. Test fails until you add the assertion
  4. 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 typeLocation
Component-specific (scroll, selection)Inside the component struct
Cross-cutting (event list, stats)app.rs
Augmentor stateInside augmentor struct, NOT global

❌ NEVER add component-specific state to app.rs. Components own their state.

Critical Anti-Patterns

  1. app.rs bloat — Don't add theme_list_scroll, panel_selected_index to App. Put in component.
  2. Duplicating behavior — Extract to trait with default impl, not copy-paste.
  3. Coupling component→view — Components return data; views decide what to do.
  4. Mixing render+state — State structs return data; impl Renderable handles 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-1

Before 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/ vs tui/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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.