ottyl/AGENTS.md

AGENTS.md

Codebase Intelligence for ottyl (Repowise)

Indexed by Repowise. Last indexed: 2026-09-07 (commit 0c41048). Confidence: 98%.

How to work in this repo

• Trust the index. verified: true means the bytes were checked against the live tree, so never re-read those lines. Re-read only on bounds: "approximate", _meta.stale_warning, search_method: "bm25" or confidence: "low"; index_behind: true alone is informational.
• Pre-edit, not instead-of-edit. These tools decide which files to read and edit. Reading a file before you edit it is correct and expected.
• Noisy commands (tests, builds, git log/diff, searches, listings): prefer repowise distill <cmd>, the same command with its exit code preserved and errors-first output. A [repowise#<ref>: N lines omitted] marker is recoverable via repowise expand <ref> (add -q <regex> to filter); never re-run the command to see omitted output.
• Recording a decision you had to reason out: repowise decision add --title T --decision D records it without prompting and prints the id (--format json to parse it back). It lands proposed, for a person to confirm.

Tools

Tool	When and why
get_answer(question)	First call for any how/where/why question. Cite confidence: "high" or grounding: "extracted" directly; degraded means judge by retrieval_quality. symbol_bodies has live bodies.
get_context(targets=[...])	Triage card for files/modules/symbols: docs, signatures, hotspot, fix history. No source bytes — include=["skeleton"] for the whole file verified, `["callers"
get_symbol(id)	Follow-up, not an entry point — one verified body for an id a prior response named (path.py::Name, path.py:140-180, repowise#<hex>). Never walk a file symbol by symbol; Read it.
search_codebase(query)	Hybrid search, auto-routed by query shape; force with `mode=symbol
get_why(query, targets?)	Why the code is shaped this way: decision records, git archaeology, rationale comments. Call before a refactor or a pattern divergence.
get_risk(targets, changed_files?)	What history says about touching these files. PR mode (changed_files) leads with a directive: read will_break / missing_cochanges / missing_tests / tests_to_run first.
get_change_risk(revspec, extensions?, exclude_patterns?)	Defect score for a whole commit or base..head range, from its diff on the live checkout. Lead with risk_percentile. Scores a range; get_risk scores paths.
get_health(targets?, include?)	Defect / maintainability / performance scores and findings. Self-check the files you touched before finishing.
get_dead_code()	Confidence-tiered unreachable files / unused exports / zombie packages. For cleanup sweeps, not targeted fixes.
get_overview()	Architecture map. Call once, first, in an unfamiliar repo; skip it after that.

Architecture

ottyl ingests log & metric streams -> processes via Rust engine (parsing, filtering, PromQL) -> outputs visualized data via TypeScript web UI.

Key modules

• root — What the prose above calls things, the identifier to search for, and where it lives

Entry points

• src/main.rs
• webapp/src/main.tsx
• webapp/src/App.tsx

Files that need care (bug-fix history first, then churn — check get_risk before editing)

• webapp/src/App.tsx — 3 bug fixes, last fix today; 22 commits/90d
• webapp/src/components/Dashboards.tsx — 3 bug fixes, last fix today; 17 commits/90d
• webapp/src/lib/api.ts — 1 bug fix, last fix today; 41 commits/90d
• webapp/src/components/NavMenu.tsx — 1 bug fix, last fix today; 22 commits/90d
• webapp/src/components/Docs.tsx — 1 bug fix, last fix today; 16 commits/90d

Code health

Three co-equal signals: defect risk 7.53/10 avg, hotspot health 7.15/10 (stable), worst src/engine/snapshot/mod.rs at 5.5/10 · maintainability 7.91/10 · performance risk 21 open static I/O-in-loop / N+1 findings. Detail: get_health().

Critical files:

• webapp/src/components/NavMenu.tsx — churn risk — impact −2.4
• src/engine/tests.rs — churn risk — impact −2.4
• src/engine/mod.rs — churn risk — impact −2.4
• src/config/mod.rs — churn risk — impact −2.4
• src/api/dto.rs — churn risk — impact −2.4

Commands

• Build: make build
• Test: make test
• Lint: make lint
• Dev: make dev