tunacode
AGENTS.md125 starsChanged 10 months agoMITView on GitHub
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repositoryOne other file it gives its agents.
- pypi-releaseSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
18 rules. About 0 are common, 9 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 23
Use it as the operational checklist for what runs locally vs what is enforced in CI.
- Very specific: line 26
Follow docs/git/practices.md for local Git workflow and safety rules.
- Very specific: line 27
Use docs/git/changelog-update.md when the task is to refresh CHANGELOG.md from recently merged PRs.
- Very specific: line 28
Before performing any Git operation (git status, git add, git commit, etc.), read docs/git/practices.md in that session.
- Distinctive: line 29
Default behavior is non-destructive: never delete or clean untracked files/directories unless explicitly requested by the user.
- Distinctive: line 30
If unknown files appear during checks, pause and ask before cleanup.
- Very specific: line 62
Import ordering test: tests/architecture/test_import_order.py.
- Very specific: line 117
Keep AGENTS.md updated with Last Updated: YYYY-MM-DD whenever src/ or docs/ changes.
- Very specific: line 119
Do not add TunaCode-owned message-contract wrappers around tinyagent message types.
- Very specific: line 121
Treat current file-length allowlist entries as temporary debt only.
- Distinctive: line 122
Do not edit unrelated local changes unless scoped to the task.
- Distinctive: line 123
Never delete untracked files/directories (or run destructive cleanup) without explicit user confirmation.
- Very specific: line 124
Avoid adding empty directories or __init__.py-only directories.
- Distinctive: line 127
Prefer small, scoped changes.
- Distinctive: line 128
Keep edits minimal and targeted.
- Distinctive: line 129
Prefer existing patterns; mirror command/test naming used in nearby code.
- Very specific: line 130
Treat src/tunacode/ui/render_safety.py plus built-in theme wrapping in src/tunacode/constants.py as part of the startup/theme stability …
- Distinctive: line 131
Run validation commands before handoff when touching architecture, dependencies, or shared packages.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.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
AGENTS.md
Last Updated: 2026-07-10
Repository Orientation
- This is
tunacode-cli, a terminal AI coding agent with a Textual UI and tiny-agent tool loop. - Primary source package:
src/tunacode/. - Python requirement: 3.11+ (
pyproject.toml). - We use UV and .venv
Start Here
docs/modules/index.md— module layer map and reading order.docs/architecture/dependencies/DEPENDENCY_LAYERS.md— generated dependency summary.docs/skills/audit-harness/SKILL.md— strict harness-audit procedure; treat any mismatch or failed gate as critical and run checks manually one by one.docs/modules/ui/commands.md— command model and command registration notes.docs/workflows/README.md— accepted development workflows and execution guidance.scripts/check_agents_freshness.py— validates this file is current.
Harness Documentation Purpose
HARNESS.mddocuments the code-quality harness for this repository.- It captures pre-commit, pre-push, repository rules, and CI/CD checks in one place.
- The goal is to balance developer speed with reliability when programming with code agents.
- Use it as the operational checklist for what runs locally vs what is enforced in CI.
Git Safety and Non-Destructive Defaults
- Follow
docs/git/practices.mdfor local Git workflow and safety rules. - Use
docs/git/changelog-update.mdwhen the task is to refreshCHANGELOG.mdfrom recently merged PRs. - Before performing any Git operation (
git status,git add,git commit, etc.), readdocs/git/practices.mdin that session. - Default behavior is non-destructive: never delete or clean untracked files/directories unless explicitly requested by the user.
- If unknown files appear during checks, pause and ask before cleanup.
- During commit-time check failures, do not make architectural/refactor decisions to force a green commit; only apply trivial lint-only fixes, otherwise stop and ask for user instruction.
Top-Level Layout
src/tunacode/— application code.tests/— unit and architecture tests.docs/— module documentation and architecture artifacts.scripts/— local tooling and validation scripts..github/workflows/— CI gates and release workflows.Makefile— developer-facing command shortcuts.pyproject.toml— package metadata, deps, lint/type/security settings.
Entry Points
- App entry:
src/tunacode/ui/main.py(Typer app attunacodescript). pyproject.toml:[project.scripts]->tunacode = "tunacode.ui.main:app".- Developer entry:
Makefiletargetmake run->uv run tunacode.
Source Structure (high-level)
src/tunacode/ui/— terminal UI, widgets, screens, CSS, command shell, and render-safety helpers for Rich/Textual theme stability.src/tunacode/core/— agents, compaction, session, prompting, logging.src/tunacode/tools/— native tinyagent tool implementations (bash,discover,read_file,hashline_edit,web_fetch,write_file) plus supporting helpers.src/tunacode/configuration/— settings, model registry, API paths, limits, pricing, and ignore patterns.src/tunacode/infrastructure/— caches and managers.src/tunacode/utils/— adapters, messaging helpers, token counting, gitignore, system utilities.src/tunacode/types/— canonical data models, callbacks, protocol types.- Shared packages:
src/tunacode/constants.py,src/tunacode/exceptions.py,src/tunacode/skills/,src/tunacode/prompts/. - Notable sub-packages:
src/tunacode/core/ui_api/(core→UI bridge).
Architecture Boundaries
- Documented conceptual stack (bottom-up):
types -> utils -> infrastructure -> configuration -> tools -> core -> ui. - Architectural enforcement test:
tests/test_dependency_layers.py.- Allowed import direction:
ui -> core -> tools, with shared-layer imports fromutils,types,configuration,constants,exceptions.
- Allowed import direction:
- Import ordering test:
tests/architecture/test_import_order.py.- Layer order constant includes shared modules (
configuration, constants, exceptions, prompts, skills, types, utils) then layered modules (tools, infrastructure, core, ui).
- Layer order constant includes shared modules (
- Public-init constraint:
tests/architecture/test_imports_in_init.py. - Dependency map regeneration pipeline:
scripts/grimp_layers_report.py, committed todocs/architecture/dependencies/by workflow.
Documentation Sources to Trust
- Primary runbook:
README.md. - Architectural map:
docs/modules/index.md. - Review notes for active PR triage:
docs/reviews/. - Debugging and investigation artifacts:
docs/reviews/*-artifact.md. - Git workflow and safety practices:
docs/git/practices.md. - Changelog refresh procedure for merged PR summaries:
docs/git/changelog-update.md. - Workflow guidance:
docs/workflows/README.mdand workflow-specific files such asdocs/workflows/REFACTOR.md. - Module-specific docs:
docs/modules/core/core.mddocs/modules/ui/ui.mddocs/modules/tools/tools.mddocs/modules/tools/hashline-subsystem.mddocs/modules/configuration/configuration.mddocs/modules/configuration/models-registry.mddocs/modules/infrastructure/infrastructure.mddocs/modules/types/types.mddocs/modules/utils/utils.mddocs/modules/skills/skills.md
- UI design reference:
docs/ui/css-architecture.mdand generated map atdocs/codebase-map/structure/tree-structure.txt.
Routine Commands
- Setup:
make install(canonical full dev environment bootstrap).- Installs repo-managed
pre-commitandpre-pushgit hooks from.githooks/.
- Installs repo-managed
- Compatibility alias:
make dev-setup. - Run app:
make run. - Full tests:
make test. - Linters + hooks:
make lint. - Focused checks:
uv run pre-commit run --all-filesuv run pytestuv run pytest tests/test_dependency_layers.py -vuv run pytest tests/architecture/test_import_order.pyuv run pytest tests/architecture/test_imports_in_init.pyuv run python scripts/run_gates.pyuv run python scripts/check_agents_freshness.pyuv run python scripts/generate_structure_tree.py
CI and Release Signals
- Lint/security pipeline:
.github/workflows/lint.yml. - Dependency map updates:
.github/workflows/dependency-map.yml. - Tech debt scans:
.github/workflows/tech-debt.yml. - Version/release checks:
uv run python scripts/generate-release-notes.sh(auxiliary script usage in repo)- release workflows:
release.yml,publish-release.yml.
- Additional hygiene:
.github/workflows/empty-dir-check.ymlfor dead directories.
Quality Constraints (Do not break)
README.mdand docs should stay consistent with implementation.- Keep
AGENTS.mdupdated withLast Updated: YYYY-MM-DDwheneversrc/ordocs/changes. - The 2026-04-13 getattr baseline follow-up reduced the scoped UI/runtime and owned-exception
getattr(...)usage; the committed ast-grep baseline should stay aligned with those removals. - Do not add TunaCode-owned message-contract wrappers around tinyagent message types; use tinyagent models directly in memory and keep dict payloads at real boundaries.
- Preserve existing architecture order rules; do not add new imports across forbidden layers.
- Treat current file-length allowlist entries as temporary debt only. Do not add any new file-specific exemptions to the
>600line rule; fix the enforcement path or split the code instead. - Do not edit unrelated local changes unless scoped to the task.
- Never delete untracked files/directories (or run destructive cleanup) without explicit user confirmation.
- Avoid adding empty directories or
__init__.py-only directories.
Editing Guidance
- Prefer small, scoped changes.
- Keep edits minimal and targeted.
- Prefer existing patterns; mirror command/test naming used in nearby code.
- Treat
src/tunacode/ui/render_safety.pyplus built-in theme wrapping insrc/tunacode/constants.pyas part of the startup/theme stability path; keep Rich default/ANSI color handling local to TunaCode rather than patching Textual. - Run validation commands before handoff when touching architecture, dependencies, or shared packages.
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.

