Global Agent Context
Personal dev environment optimized for LLM-maintained codebases. All code is written and read by AI agents—optimize for model reasoning, regeneration, and debugging, not human aesthetics.
Prefer nushell over bash for data processing—structured pipelines, not text munging.
LLM-First Code Philosophy
The Goal: Code that future LLMs can confidently rewrite, extend, or debug without context archaeology.
What Matters
PriorityWhySimple entry pointsAgent can locate where to start without tracing importsExplicit over abstractNo hidden magic; what you see is what runsMinimal couplingFiles can be regenerated independentlyLinear control flowEasier to trace, fewer state machines to reconstructStructured logs at boundariesDebugging without stepping through codeDeclarative configJSON/YAML over code-based setup
What Doesn't Matter
Perfect variable names (agents parse structure, not prose)
Human-friendly formatting (agents don't skim)
Comments explaining what (code is self-evident to LLMs)
DRY abstractions that hide behavior (duplication is fine if explicit)
Mandatory Patterns
Structure — Group by feature/screen. Shared utilities minimal. Identify shared structure before scaffolding (layouts, providers, base templates). Duplication requiring same fix in multiple places = code smell.
Architecture — Flat and explicit. No metaprogramming, clever patterns, or deep hierarchies. Coupling low enough that any file can be safely regenerated.
Functions — Small-to-medium, linear flow. Pass state explicitly. No globals. Avoid deep nesting.
Comments — Only for invariants, assumptions, or external requirements. Never explain what—only why when non-obvious.
Errors & Logs — Detailed structured logs at key boundaries. Errors explicit and informative. This is how agents debug.
Regenerability — Every file/module can be rewritten from scratch without breaking the system. Prefer full-file rewrites over surgical edits.
Platform Use — Use framework conventions directly (TanStack Router/Start, Effect, React, etc.) without wrapping layers that obscure behavior.
Modifications — When extending, follow existing patterns exactly. Don't "improve" style during a feature change.
Tests — Simple, focused on observable behavior. Deterministic. No test infrastructure that's harder to understand than the code.
Tool Selection
TaskToolWhyUnderstand codebasecmap, osgrep, scip_*See dedicated section belowData/JSONnu -c '...'Tables, not text. JSON nativeFind conceptsosgrep searchSemantic search, understands meaningFind structureast-grep --lang ts -p '...'AST-aware, ignores strings/commentsFind textrg "pattern"Fast literals, regex, non-code filesFind filesfd patternBetter find, respects gitignoreGitHub reposGitChamberNo clone, targeted lookupsMarkdown notesqmdHybrid search (BM25+vector) for indexed docsFetch docsjina.read_urlAny URL → structured markdownTask trackingbd (beads)Git-backed, dependency graphsBrowserplaywriter.executeChrome automation
Code Understanding Tools (Critical)
Three complementary tools for navigating codebases. Use these before reading files line-by-line.
When to Use What
NeedToolWhy"Where is X defined?"scip_find_definitionPrecise, scope-aware, no false positives"Who calls X?"scip_find_references or cmap callersImpact analysis before changes"What's in this file?"scip_list_symbols or cmap inspectOverview before deep reading"Where do we handle auth?"osgrep searchSemantic—finds concepts, not strings"How does data flow from A to B?"cmap trace or osgrep traceCall path tracing"Project structure overview"cmap stats . + cmap map . --level 2Quick orientation"What changed since main?"cmap diff mainSymbol-level git diff"What's not tested?"cmap untested .Coverage gaps
SCIP Tools (Index-Based Navigation)
Precise symbol navigation for TypeScript/JavaScript/Python. Understands scope—no grep false positives.
scip_project_tree # Structural overview (start here on new repos) scip_find_definition <sym> # Jump to definition scip_find_references <sym> # All usages (impact analysis) scip_list_symbols <file> # Symbols in a file scip_search_symbols <query> # Find by partial name
Best for: Exact navigation, refactoring impact, "show me the definition."
osgrep (Semantic Search + Call Graphs)
Natural-language search that finds concepts, not just strings. 100% local embeddings.
osgrep search "authentication middleware" # Semantic search osgrep search "error handling" --compact # Paths only (token-efficient) osgrep trace <symbol> # Call graph for a symbol osgrep skeleton <file> # Signatures without bodies osgrep symbols [pattern] # List indexed symbols
Best for: Exploration, "where do we handle X?", understanding orchestration vs definitions.
cmap (AST-Based Structural Analysis)
Fast in-memory code analysis using tree-sitter. No database. Use --format ai for token-efficient output.
# Orientation cmap stats . # Project size/composition cmap map . --level 2 --format ai # File structure with symbol counts # Navigation cmap query <name> --fuzzy # Find symbols (always use --fuzzy) cmap inspect <file> # All symbols in a file cmap query <name> --fuzzy --show-body # See implementation # Call graphs cmap callers <symbol> # Who calls this? cmap callees <symbol> # What does this call? cmap trace <from> <to> # Shortest call path A → B # Before refactoring cmap tests <symbol> # Find tests for this cmap untested . # Uncovered code # Git integration cmap diff main # Symbol-level changes vs main cmap since v1.0 --breaking # Breaking changes since release cmap blame <symbol> <file> # Who last modified this?
Best for: Project overview, call graphs, impact analysis, git-aware code changes.
Decision Guide
New to codebase? → cmap stats . && cmap map . --level 2 --format ai → scip_project_tree Looking for a concept ("where do we handle X")? → osgrep search "X" Looking for exact symbol? → scip_find_definition or cmap query --fuzzy Understanding impact before changing? → scip_find_references + cmap callers Tracing data/control flow? → cmap trace or osgrep trace
Nushell (nu)
Why: Structured data. Tables not text. Type-safe. JSON native. No grep/awk/sed chains.
# Files by size nu -c 'ls | where size > 1MB | select name size' # JSON without jq nu -c 'open package.json | get dependencies | transpose name version' # Recent TypeScript files nu -c 'ls **/*.ts | where modified > ((date now) - 1day) | get name' # HTTP + transform nu -c 'http get $url | get data.items | where status == "active"'
Bash → Nushell Quick Reference
BashNushellNotesgrep patternwhere $it =~ pattern or find patternStructured filtersed 's/a/b/'str replace a bString opsawk '{print $1}'get 0 or select colColumn accessjq '.key'get keyJSON nativefind . -name "*.ts"ls **/*.tsGlob built-inxargs cmdeach { cmd $in }Iterationcat fileopen fileStructured read> file| save fileRedirect>> file| save -a fileAppend> /dev/null| ignoreDiscard$VAR$env.VAREnv varsexport FOO=bar$env.FOO = "bar"Set env$(cmd)(cmd)Subshell"Hello $name"$"Hello ($name)"Interpolationcmd1 && cmd2cmd1; cmd2Sequence
$in in closures (not $it): each { $in * 2 }
^git for external commands
Row conditions auto-expand: where size > 1MB = where $it.size > 1MB
Load nushell skill for full patterns.
MCPorter (MCP via CLI)
Calls MCP servers from CLI. Available servers: playwriter (browser), jina (web), repoprompt (codebase).
bunx mcporter list <server> # List tools bunx mcporter call '<server>.<tool>(...)' # Call tool
Jina — Web Search & URLs
bunx mcporter call 'jina.search_web(query: "AI developments")' bunx mcporter call 'jina.read_url(url: "https://example.com")' bunx mcporter call 'jina.search_arxiv(query: "transformers")'
Playwriter — Browser Automation
Controls Chrome via extension. Requires extension installed + clicked on target tab.
bunx mcporter call 'playwriter.execute(code: "console.log(page.url())")' bunx mcporter call 'playwriter.execute(code: "console.log(await accessibilitySnapshot({ page }))")' bunx mcporter call 'playwriter.execute(code: "await page.locator(\"aria-ref=e14\").click()")'
RepoPrompt — Codebase Tools
bunx mcporter call 'repoprompt.tree()' bunx mcporter call 'repoprompt.structure(path: "src/")'
GitChamber (GitHub without cloning)
When: Need < 10 files from external repos. Fast, no disk, always latest.
# List files curl -s "https://gitchamber.com/repos/{owner}/{repo}/{branch}/files" # Get content curl -s "https://gitchamber.com/repos/{owner}/{repo}/{branch}/files/{path}" # Search curl -s "https://gitchamber.com/repos/{owner}/{repo}/{branch}/search/{query}" # All files (small repos only) curl -s "https://gitchamber.com/repos/{owner}/{repo}/{branch}/files?glob=**/*"
Need 10+ files? → git clone --depth 1 to /tmp
QMD (Markdown Search)
When: Searching indexed markdown (notes, docs, meeting transcripts).
qmd search "topic" # Fast keyword (BM25) qmd vsearch "how to X" # Semantic search qmd query "concept" --min-score 0.4 # Hybrid + reranking (best) qmd get "#docid" # Fetch by ID from search results qmd search "X" --all --files --min-score 0.3 # Agent export
vs osgrep: osgrep searches code repos; qmd searches personal markdown collections with local embeddings.
Task Tracking (bd)
Use bd instead of markdown TODOs. Git-backed, dependency-aware.
bd ready # Find unblocked work bd create "Title" -t task -p 2 # Create task bd close bd-xxx --reason "Done" # Complete
Load beads skill for full reference.
Background Processes (tmux)
tmux new-session -d -s name 'cmd' # Start background tmux capture-pane -t name -p # View output tmux send-keys -t name C-c # Interrupt tmux kill-session -t name # Stop
Multi-Agent Coordination
Agent Mail: File reservations and messaging between agents.
Workflow: bd ready → reserve files → work → bd close → release
Agent Workflow Principles
Verify before returning — Run tests, check builds. Never return incomplete work.
Update context files — After learning something important, update .ruler/agents.md or sibling context files. These can be regenerated.
Reuse terminals — Close unneeded terminals. Don't spawn endlessly.
Check docs first — Fetch current docs using GitChamber (GitHub repos) or Jina via MCPorter (any URL → structured markdown). Training data is stale.
Work in discrete steps — Use subagents to keep main context window clean.
Prefer full rewrites — Surgical edits accumulate cruft. When in doubt, regenerate the file.
Anti-Patterns (Don't Do This)
PatternProblemDeep abstraction layersAgents must trace through indirection to understandMagic/metaprogrammingBehavior isn't in the code agents readMicro-edits to fix micro-issuesAccumulates inconsistency; regenerate insteadComments explaining obvious codeNoise; agents read code faster than commentsDRY at the cost of localitySpreading logic across files = more context neededClever naming conventionshandleXyzForAbcWhenDef doesn't help agents
Skill Pointers
NeedSkill to LoadBrowser automationdev-browserNushell patternsnushellCode searchosgrepGitHub accessgitchamberTask trackingbeadsContext buildingrepoprompt