AgentTokenInsight

AgentTokenInsight is a Java CLI and reusable library for coding-agent task scope, context budget, and safety guardrails. It can scan a repository, estimate token usage, validate the result against configured rules, and classify shell commands by risk.

Installation

Java 25 is required.

Install the CLI with npm:

npm install -g agenttokeninsight

Run the short command after global install:

agenttoken --help

Or invoke the package without a global install:

npx agenttokeninsight --help

Prerequisites

• Java 25
• A shell that can run the Gradle wrapper for building and testing

Build and Test

From the repository root:

./gradlew build

To run the test suite:

./gradlew test

To run the CLI help output:

./gradlew :agenttoken-cli:run --args="--help"

Packaging the CLI

Use the Gradle-built distribution mainly for local development or testing:

./gradlew :agenttoken-cli:installDist

Gradle is only needed to build and test the project. After installDist runs, you can use the packaged CLI without Gradle.

The generated runnable scripts are written to:

agenttoken-cli/build/install/agenttoken/bin/

Run the CLI directly from that directory:

agenttoken-cli/build/install/agenttoken/bin/agenttoken --help
agenttoken-cli/build/install/agenttoken/bin/agenttoken init
agenttoken-cli/build/install/agenttoken/bin/agenttoken scan

Running the CLI

The CLI entry point is agenttoken.

Initialize configuration

Create a starter agenttoken.yml in the current directory:

agenttoken init

Create a config tuned for a common stack:

agenttoken init --profile java
agenttoken init --profile java-ee
agenttoken init --profile node

Scan a repository

Scan the current directory:

agenttoken scan

agenttoken scan prints Markdown by default. JSON output is also available for automation workflows.

The Markdown report now includes an Insights section when the scan reveals readiness issues such as oversized scopes, blocked paths, empty scans, or low-value generated content.

Token estimates are deterministic and approximate, not exact model-specific token counts. They may differ from Claude, Codex/OpenAI, Gemini, or other model tokenizers, so it is a good idea to leave a safety margin in maxContextTokens.

Scan and request JSON output:

agenttoken scan --format json

Scan an explicit task scope

Use agenttoken scope when you want to analyze a focused task scope instead of the whole repository.

Examples:

agenttoken scope --include src
agenttoken scope --include src --include test
agenttoken scope --include src --exclude src/generated
agenttoken scope --include src --format json

agenttoken scope loads agenttoken.yml from the current directory, scans only the included paths, applies configured ignored paths and command-line excludes, and validates the result against the loaded budget config.

Generate a brief for an AI coding agent

Use --brief when you want a deterministic Markdown/text brief that you can paste into an AI coding agent.

Examples:

agenttoken scan --brief
agenttoken scope --include src --brief

The brief includes the allowed scope, ignored and excluded paths, budget status, key insights, and an instruction to ask before expanding scope.

--brief cannot be combined with --format json.

Check a shell command

Classify a command for risk:

agenttoken check-command "rm -rf build"

Sample agenttoken.yml

Use the following file as a starting point:

maxContextTokens: 12000
maxFilesPerTask: 15
ignoredPaths:
  - .git
  - .gradle
  - .idea
  - build
  - target
  - out
  - logs
  - node_modules
  - dist
  - coverage
blockedPaths: []
allowedWritePaths: []
blockedCommands: []

What AgentTokenInsight Does

AgentTokenInsight helps you:

• scan repository files and estimate token usage
• analyze explicit task scopes with agenttoken scope
• validate scans against budget rules
• generate Markdown or JSON scan reports
• surface deterministic readiness insights in scan reports
• generate deterministic agent briefs for AI coding-agent handoff
• assess shell command risk before running destructive commands

Token counts are deterministic approximate estimates, not exact model tokenizer outputs. Treat them as a planning signal rather than a precise billing or context guarantee.

Markdown is the default scan output. JSON output is available when you need machine-readable results for scripts, CI jobs, or other automation.

Default ignored paths include .git, .gradle, .idea, build, target, out, logs, node_modules, dist, and coverage.

Development Workflow

AgentTokenInsight is developed with a lightweight Spec-Driven Development workflow.

The project keeps current behavior in spec/current/, active changes in spec/changes/, and completed change history in spec/archive/.

For the reasoning behind this workflow, see: Specs as Boundaries: A Lightweight SDD Workflow for AI Coding Agents