A terminal CLI that scores how easy your repo is for AI agents and humans to understand, change, and trust. Run it in a repo to get an operability score, structural risks, and the highest-friction areas to fix first.
Interactive health report in one pass.
Surfaces the kinds of problems that slow down both engineers and coding agents: oversized files, weak boundaries, missing docs and tests, generic naming, and high-coupling modules. Output is deterministic and terminal-native.
agento health— overall score (0–100), letter grades per section, interactive navigator (arrow keys + Enter)agento health --summary— full breakdown: weighted subscores, hotspots, task-friction warnings, recommended fixesagento health --format json— machine-readable for CI or scripts
git clone <your-repo-url>
cd agento
pnpm install
pnpm build
node ./dist/cli/index.js healthThis makes agento available as a command on your machine during development.
pnpm install
pnpm build
pnpm link --global
agento healthUseful for local distribution or release packaging.
pnpm package:tarballThis creates a package tarball like agento-0.1.0.tgz.
If you are preparing a release, you can generate a Homebrew formula after producing a tarball URL:
pnpm formula ./agento-0.1.0.tgz https://github.com/your-org/agento/releases/download/v0.1.0/agento-0.1.0.tgzThat writes Formula/agento.rb.
Run inside any repository:
agento healthOr without linking:
node ./dist/cli/index.js healthFor CI, scripts, or machine-readable workflows:
agento health --format jsonFor the expanded report instead of the compact interactive overview:
agento health --summaryagento --help+-----------------------------------+
| AGENTO AI OPERABILITY |
| Score: 62/100 (Needs work) 🟠 |
+-----------------------------------+
Subscores
- Code Discoverability
- Context Density
- Architectural Legibility
- Blast Radius
- Change Safety
- Agent Taskability
- Documentation Surface
Task Friction Warnings
- No test framework detected
- No architecture documentation detected
- Large files increase patch risk
- Audit a repo before handing it to Codex, Claude, or another coding agent
- Identify what makes AI edits risky before a sprint
- Add health checks to internal engineering workflows
- Track maintainability issues that make onboarding slower
- Create a shared quality language around structure, docs, and safety
pnpm install
pnpm build
pnpm devUseful commands:
pnpm build- Compile TypeScript todist/pnpm dev- Run the CLI from source withtsxpnpm health- Alias for local health command executionpnpm package:tarball- Build and package the CLIpnpm formula- Generate a Homebrew formula
Agento is intentionally focused on one primary wedge right now:
- A deterministic AI operability and repository health score
That means the emphasis today is on trustworthy scanning, clear terminal output, and actionable findings rather than AI-generated narration.
Internal groundwork exists for future commands and config-driven workflows, but they are not public CLI commands yet.
Near-term direction:
agento initagento context --write- stricter architectural rules
- richer config support through
agento.json - more CI-friendly reporting
- add an “agent recommendation mode”
- Prefer narrow tasks against isolated components
- Avoid asking agents to “refactor navigation” in one shot
- For form work, first ask the agent to map field definitions and validation boundaries
- For root-shell changes, force a plan-first workflow before edits
- Taskability Assessment
- Recommended AI Working Style
Current health categories:
- Code Discoverability
- Context Density
- Architectural Legibility
- Blast Radius
- Change Safety
- Agent Taskability
- Documentation Surface
Agento is not trying to replace general AI assistants.
It is meant to complement them:
- Codex helps you work in a repository
- Agento helps you understand whether that repository is easy to work in, why it is not, and what to fix first
MIT