- These rules apply to all agent work in this repository.
- Requests to review, analyze, or explain are read-only unless the user also asks for changes.
- Read every focused guide whose route matches the task before editing files.
- More specific instructions override broader ones.
- Keep
CLAUDE.mdas a symlink to this file. Record new durable rules here or in the matching focused guide.
| Task or path | Read before editing |
|---|---|
| Features, bug fixes, tests, or test helpers | docs/agents/testing.md |
| SQLite, PostgreSQL, CockroachDB, DuckDB, ClickHouse, archive resync, or storage queries | docs/agents/storage.md |
| Watchers, polling, sync scheduling, background work, or memory investigations | docs/agents/background-work.md |
| Build commands, toolchains, CI build tags, or dependencies | docs/agents/build.md |
S3 ingest, S3Provider, or Source.S3Discovery |
docs/agents/s3-providers.md |
| Any frontend file | frontend/AGENTS.md |
| Frontend controls, styling, or reusable components | frontend/AGENTS.md and DESIGN.md |
The README.md and Makefile are the sources for project facts, setup, and
commands. Do not copy their catalogues into this file.
For CI runner selection and caching, read the CI runner policy.
- Never run
roborev reviewunless the user asks for it. - Never invoke a roborev skill, including
roborev-fixorroborev-design-review-branch, unless the user asks for that skill. - Other roborev commands may be used when they fit the task.
- Check the branch state before editing. Do not create or switch branches without the user's permission. A Codex-managed detached worktree may receive commits; leave branch creation to the user or app.
- Commit every turn that changes tracked files. Do not make empty commits. If a turn is read-only or changes only ignored files, say that no commit was made.
- Keep commits focused and use clear conventional commit messages.
- Do not amend, squash, rebase, push, or pull unless the user asks.
- Do not add generated-with lines, attribution blocks, validation footers, or command transcripts to commit messages.
- Deliver changes through pull requests from feature branches. Never merge a pull request; merging is the user's decision.
- Do not revert user work or unrelated local changes unless the user asks.
- Avoid destructive git commands unless the user asks.
- Never install over a live binary, run migrations against production, or write to live data directories without permission. Use isolated scratch data for branch builds and profiling.
- For login or OAuth, give the user the exact command instead of driving the interactive flow.
- SQLite is the persistent archive. Never delete, drop, truncate, or recreate it
to handle data-version changes. Read
docs/agents/storage.mdbefore any archive, database, parser-resync, or storage change.
- Keep private project names, hostnames, personal identities, infrastructure details, and absolute user paths out of code, tests, fixtures, documentation, commit messages, and pull request text. Run the private-data scrub before publishing.
- Write changelog entries in plain language for people who do not live in the codebase. Lead each entry with the outcome a user or operator will notice. Put implementation details after that outcome, and include them only when they help the reader act or understand a limit.
- Keep pull request titles and descriptions in sync with the current diff.
- Do not post pull request or issue comments unless the user asks.
- Write for the person trying to use or maintain AgentsView. Lead with the outcome, name who does what, use short sentences, and explain unfamiliar terms.
- Organize around reader questions. Put purpose and current capabilities first; separate limitations and future work. Use only the sections the topic needs.
- Give each bullet one main idea. Use numbered steps for sequences, paragraphs for rationale, and tables or diagrams when they clarify a comparison or flow.
- State rules directly. Preserve exact commands, field names, authorization checks, limits, and failure behavior when simplifying the wording.
- Give each fact an owning guide or reference and link to it elsewhere. Update that section instead of appending a narrative of the latest change. Indexes should route readers, not repeat implementation status.
- Describe current architecture separately from approved but unbuilt work, proposals, and historical decisions. Preserve rationale, approvals, and active exceptions with their removal conditions. Label superseded designs and keep them outside normal navigation.
- Keep the website, its Markdown companions, README, and documentation on
message. Distinguish the latest release from newer
mainfunctionality. Follow docs/README.md for the publishing layout and checks. - Verify release notes against the release tags and source. Credit contributors from merged pull requests or commit history; do not infer contributions from names or issue participation alone.
- Regenerate the full screenshot set for every release and store it on the
docs-generated-assetsorphan branch. Add captures for new visible features, inspect the images, and preview the assembled website locally before opening the release documentation pull request. Followdocs/screenshots/README.md.
- Follow every focused guide matched by the task routes above.
- Run relevant checks before committing when practical. If a check cannot run, state that in the handoff.
- After changing Go code, run
go fmt ./...andgo vet ./...before committing. - Preserve observable behavior and update documentation when behavior changes.
When adding a provider, changing its format or usage/cost accounting, or
investigating a provider release, new artifact generation, parser bug, or usage
discrepancy, consult docs/internal/session-format-sources.md and reverify or
update its evidence entry in the same change. Grok remains temporarily excluded
only until its separately owned format-alignment work lands.
agentsview syncs local AI agent sessions into SQLite, serves a Svelte 5 web UI, and can mirror data to PostgreSQL, DuckDB, or ClickHouse.
cmd/agentsview/: CLI and server entry pointsinternal/db/: SQLite archive and searchinternal/readbase/: shared replica and mirror catalog, analytics, session and transcript reads, and read-only stubsinternal/postgres/: PostgreSQL sync and read storeinternal/duckdb/: disposable DuckDB mirror and Quack readsinternal/clickhouse/: ClickHouse remote mirror and read storeinternal/parser/: agent session parsersinternal/server/: HTTP API and SSEinternal/sync/: discovery, file watching, and syncinternal/vector/: semantic and hybrid searchfrontend/: Svelte 5 application
- Prefer the standard library over new dependencies.
- Use
internal/stringutil.SafeTruncatefor byte-limited display text. Add truncation markers at the call site and reserve their bytes when the limit includes them. Useinternal/stringutil.TruncateRunesfor rune-count limits; its limit excludes the supplied suffix. Keep rune-count limits distinct from byte limits. Both helpers assume valid UTF-8 and do not sanitize malformed input. - Do not use emojis in code or output.
- Format Markdown with
mdformat --wrap 80whenmdformatandmdformat-tablesare available.
- Pull requests must have a user-facing benefit or improve the developer experience, and the body must say which one.
- Write issues and pull requests in English.
- Do not poll or watch GitHub Actions checks unless the developer explicitly requests it.
- Do not use
gh apito watch CI jobs unless the user explicitly requests it. - Write summary-only pull request descriptions. Do not add test plans, checklists, command transcripts, or sections named Tests, Testing, Verification, or Test plan.
- Explain what the code does now, why it changed, tradeoffs, limits, and where reviewers should look.