🤖 AI Dev Tools (adt)

Token-efficient CLI for AI agents and developers

5-7× less token usage than JSON • 94 commands • Cross-platform

Features • Quick Start • Commands • Examples • API

📖 Overview

AI Dev Tools (adt) is a revolutionary CLI tool designed specifically for AI agents and developers who want maximum efficiency. By using intelligent output formatting, adt achieves 5-7× token savings compared to traditional JSON output while maintaining full human readability.

🎯 Perfect For

AI Agents (Claude, GPT-4, Copilot, Cursor) - Minimize context window usage
Developers - Lightning-fast code navigation and analysis
DevOps Engineers - Automated project analysis and health checks
Code Reviewers - Intelligent change detection and impact analysis

✨ Key Features

🚀 Token Efficiency

65-80% token savings with slim format
3 output modes: slim, normal, json
Smart truncation for large outputs
Token estimation in every response

🧠 AI-Powered Intelligence

Smart suggestions based on codebase state
Context tracking for decision history
Automated planning for complex goals
Change review before commits

⚡ Powerful Operations

94 commands across 27 categories
Command chaining with pipe operator
Parallel batch execution
Cross-platform (Windows, Linux, macOS)

🛡️ Safety First

Atomic operations with automatic rollback
Backup creation before destructive actions
Verification before editing
Git safety checks

🚀 Quick Start

Installation

# Global installation (recommended)
npm install -g @byrem6/ai-dev-tools

# Local development
npm install --save-dev @byrem6/ai-dev-tools

# Using npx (no installation)
npx @byrem6/ai-dev-tools --help

First Steps

# Check your environment
adt doctor

# Get intelligent suggestions for your project
adt smart suggest

# Explore your codebase
adt map . --fmt normal

# Initialize AI tool configs
adt init

📊 Token Efficiency Comparison

Command	JSON Output	Slim Format	Savings
`grep` (10 matches)	~280 tokens	~45 tokens	84%
`git status`	~85 tokens	~22 tokens	74%
`complexity` (20 files)	~320 tokens	~60 tokens	81%
`read` (100 lines)	~180 tokens	~35 tokens	81%
Average	-	-	~75%

🎯 Usage Examples

For AI Agents

# Session initialization
adt resume --fmt slim
adt context get --fmt slim

# Quick symbol location (slim format for minimum tokens)
adt where "UserService" src/ --fmt slim
# Output: src/services/UserService.ts:45:8

# Read specific range
adt read src/services/UserService.ts --start 45 --lines 20 --fmt normal

# Safe editing workflow
adt verify src/app.ts --lines 100:105 --contains "export function"
adt patch src/app.ts --replace 100:105 --with "export async function" --dry-run
adt patch src/app.ts --replace 100:105 --with "export async function"

For Developers

# Quick file overview
adt peek src/components/Header.ts

# Find all usages
adt refs "useEffect" src/

# Analyze complexity
adt complexity src/ --top 10

# Check project health
adt health --verbose

# Generate changelog
adt changelog --version 2.0.0

AI-Powered Workflow

# 1. Get intelligent suggestions
adt smart suggest

# 2. Track your decisions
adt context track "Use TypeScript strict mode" --reason "Better type safety"

# 3. Create implementation plan
adt smart plan "refactor authentication system"

# 4. Execute with batch operations
adt batch --file refactor-plan.txt --parallel

# 5. Review changes before commit
adt smart review

# 6. View decision history
adt context history --fmt normal

📚 Commands

🔍 Read & Navigation

# Smart file reading
adt read <file> [options]
  --start N         Start line number
  --lines N         Number of lines to read
  --around N        Read around line (context)
  --fn <name>       Read function by name
  --fmt slim|normal|json

# Quick file overview
adt peek <file> --fmt slim
# Output: TypeScript  202 lines  11.7 KB  utf-8 CRLF

# File structure
adt outline <file> --fmt slim
# Output: class UserService :45–200
#         method constructor :50–55
#         method login :57–80

# Symbol listing
adt symbols <file> --fmt slim

🔎 Search & Discovery

# Pattern search (grep-style)
adt grep "<pattern>" [path] --fmt slim
# Output: src/service.ts:45:8:async function login(

# Find files by name/pattern
adt find "*.service.ts" src/ --fmt slim

# Locate symbols
adt where "UserService" src/ --fmt slim

# Find references
adt refs "AuthService" src/ --fmt slim

# Deep search with context
adt search "login" src/ --fmt normal

🛠️ Editing & Refactoring

# Safe editing workflow
adt verify <file> --lines N:M --contains "<text>"
adt patch <file> --replace N:M --with "<new>" --dry-run
adt patch <file> --replace N:M --with "<new>"

# String replacement
adt replace "<old>" "<new>" <file> --regex

# File operations
adt create <file> --type ts|js|jsx|tsx
adt delete <file> --backup
adt move <file> <new-path> --update-imports
adt copy <source> <dest>
adt rename <old-name> <new-name> --scope project

📊 Analysis & Metrics

# Project structure
adt map [path] --fmt slim
adt tree [path] --depth 2
adt stats [path] --by-extension

# Dependency analysis
adt deps <file> --file
adt impact <symbol> --scope <path>

# Code complexity
adt complexity [path] --top 20 --action hotspot|file|debt

# Project health
adt health --verbose
# Output: score: 75/100
#         Structure: ✓
#         Documentation: ✗
#         Testing: ⚠

# Find duplicate code
adt duplicate [path] --lines 5 --no-whitespace

# Find unused code
adt unused [path] --check imports|exports|both

🧠 AI Features (NEW!)

# Smart suggestions
adt smart suggest
# Analyzes codebase and suggests next actions

# Deep analysis
adt smart analyze
# Complete codebase health and metrics

# Goal planning
adt smart plan "<goal>"
# Generates step-by-step implementation plan

# Change review
adt smart review
# Validates changes before commit

🔄 Context & Decisions (NEW!)

# Track decisions
adt context track "<decision>" --reason "<why>"

# View context
adt context get --fmt normal

# Decision history
adt context history --fmt normal

# Get AI suggestions
adt context suggest

# Search context
adt context search --query "<term>"

# Clear context
adt context clear

⚡ Batch & Automation (NEW!)

# Batch file execution
adt batch --file <batch-file> --parallel

# Inline commands
adt batch --commands "grep 'export' src/ | symbols src/index.ts"

# Batch file format:
# grep "TODO" src/
# complexity src/
# health

🐙 Git Operations

# Git status (slim format)
adt git status --fmt slim

# Git log
adt git log --limit 20 --fmt slim

# Git diff
adt git diff --staged --fmt normal

# Git commit
adt git commit --message "feat: add user auth"

# Branch management
adt git branch list
adt git branch create feature/auth

# Stash, reset, merge, tag, cherry-pick...

🧪 Quality & Testing

# Linting
adt lint [path] --fix

# Testing
adt test [file] --coverage

# Type checking
adt typecheck [path]

# Code formatting
adt format [path] --check

📝 Documentation

# Generate table of contents
adt toc <file>

# Split documentation
adt split <file> --chapters

# Generate docs
adt doc generate --all

🌐 Additional Commands

# API Endpoints
adt api-list [path]                    # List all API endpoints
adt api-find "<pattern>" [path]        # Find endpoints by pattern
adt api-routes [path]                  # Show routing details

# Architecture Rules
adt arch-rules list                    # List architecture rules
adt arch-check [path]                  # Check rule compliance
adt arch-rule-add <spec>               # Add new rule

# Code Patterns
adt pattern match "<regex>" [path]     # Match code patterns
adt tag add "<note>" <file>            # Tag code locations

# Security & Risk
adt security [path] --severity high    # Security vulnerability scan
adt risk [path] --threshold high       # Risk analysis
adt contract-check <class> [path]      # Interface contract check

# Testing & Coverage
adt coverage-report [path]             # Test coverage report

# Code Generation
adt generate-service <name>            # Generate service class
adt generate-model <name>              # Generate model/interface
adt generate-test <name>               # Generate test file

# Integrations & Migration
adt integration-list [path]            # List external APIs
adt migrate-scan <package> [path]      # Scan deprecated APIs

# Data Flow & History
adt flow-trace <symbol> [path]         # Trace data flow
adt history-file <file>                # File git history

# Workspace & Configuration
adt workspace-list [path]              # List monorepo packages
adt config-flags [path]                # List feature flags

# Documentation
adt doc coverage <file>                # Check docs coverage
adt split <file> --lines 400           # Split large docs
adt toc <file>                         # Generate TOC

# Task & Session Management
adt task create "<title>"              # Create task
adt session show                       # Show session state
adt resume                             # Resume last session

🔧 Command Categories

Category	Commands	Description
READ	read, peek, outline	Smart file reading
SEARCH	grep, find, where, search, refs	Pattern search & discovery
SYMBOL	symbols, sig, def, body, callers, callees	Symbol navigation
EDIT	verify, patch, replace, create, delete, move, copy, rename	Safe editing operations
MAP	map, tree, stats, deps, impact	Project structure & analysis
GIT	git-status, git-log, git-diff, git-blame, git-branch, git-commit, git-stash, git-reset, git-merge, git-tag, git-cherry-pick	Git operations
SHELL	exec, platform, run, env, which	Shell & system commands
QUALITY	lint, test, typecheck, format	Code quality checks
AI	ai, smart, quick, batch	AI-powered features
CONTEXT	context	Decision tracking
UTILITY	info, files, recent, duplicate, unused, health, changelog, safe	Developer utilities
DOCUMENTATION	doc, split, toc	Documentation tools
ARCHITECTURE	arch-rules, arch-check, arch-rule-add	Architecture rules
PATTERN	pattern, tag	Code patterns
SECURITY	security, risk	Security analysis
TESTING	coverage-report	Test coverage
GENERATION	generate-service, generate-model, generate-test	Code generation
API	api-list, api-find, api-routes	API endpoints
INTEGRATION	integration-list	External integrations
MIGRATION	migrate-scan	Migration tools
FLOW	flow-trace	Data flow
CONTRACT	contract-check	Interface contracts
CONFIGURATION	config-flags	Configuration
WORKSPACE	workspace-list	Monorepo workspace
HISTORY	history-file	File history
SESSION	session, resume	Session management
TASK	task	Task management
SYSTEM	init, doctor	System setup & diagnostics

💡 Pro Tips

Format Selection Guide

Situation	Best Format	Why
AI agent queries	`slim`	Minimum tokens (5-7× savings)
Grep/search results	`slim`	Classic format, parseable
Human reading	`normal`	Balanced, readable
Code review	`normal`	Rich context, structured
Nested analysis	`json`	Required for complex data
Programmatic use	`json`	Easy to parse

AI Agent Best Practices

# 1. Always use slim for location queries
adt where "symbol" src/ --fmt slim

# 2. Use normal for content you'll analyze
adt read file.ts --start 100 --lines 50 --fmt normal

# 3. Batch operations for efficiency
adt batch --file commands.txt --parallel

# 4. Track context for better suggestions
adt context track "Working on auth feature"

# 5. Use smart suggestions when stuck
adt smart suggest

Token Optimization

# ❌ Inefficient ( wastes tokens)
adt read large-file.ts --fmt json
# Output: ~2000 tokens

# ✅ Efficient (saves 80% tokens)
adt read large-file.ts --start 100 --lines 50 --fmt slim
# Output: ~400 tokens

📦 API & Integration

Programmatic Usage

const { ExecCommand } = require('@byrem6/ai-dev-tools');

// Use adt in your Node.js scripts
const exec = new ExecCommand();
const result = await exec.execute('npm', 'test', '--fmt', 'slim');
console.log(result.content);

VS Code Integration

// settings.json
{
  "terminal.integrated.defaultProfile.windows": "PowerShell",
  "terminal.integrated.profiles.windows": {
    "adt": {
      "path": "adt",
      "args": []
    }
  }
}

GitHub Actions

- name: Code Analysis
  run: |
    npm install -g @byrem6/ai-dev-tools
    adt health --exit-on-error
    adt complexity src/ --fail-above 15

🎨 Output Formats

Slim Format (Token-Optimized)

ok true
src/services/UserService.ts:45:8:async function login(
src/controllers/AuthController.ts:78:12:login(
tests/UserService.test.ts:23:5:login(
---
count: 3  ~tokens: 45

Normal Format (Human-Readable)

ok: true
command: grep
pattern: login
===

src/services/UserService.ts:45:8
  async function login(
    username: string,
    password: string
  ): Promise<User>

src/controllers/AuthController.ts:78:12
  login(
    req: Request,
    res: Response
  )

---
matches: 2  files: 2  ~tokens: 120

JSON Format (Programmatic)

{
  "ok": true,
  "command": "grep",
  "pattern": "login",
  "matches": [
    {
      "file": "src/services/UserService.ts",
      "line": 45,
      "col": 8,
      "text": "async function login("
    }
  ],
  "metadata": {
    "count": 2,
    "files": 2
  }
}

🛠️ Configuration

Config File Location

~/.adt/config.json

Default Config

{
  "defaultFmt": "normal",
  "defaultLines": 100,
  "maxCatLines": 500,
  "maxGrepResults": 100,
  "backupRetentionDays": 7,
  "excludeByDefault": [
    "node_modules/**",
    "dist/**",
    ".git/**",
    "coverage/**"
  ],
  "tokenWarningThreshold": 1000,
  "autoBackup": true,
  "defaultShell": "auto",
  "gitSafetyChecks": true,
  "patchVerifyBeforeApply": true
}

🤝 AI Tool Integration

Supported Tools

# Auto-generate configs for all tools
adt init

# Specific tools
adt init --tools claude
adt init --tools cursor
adt init --tools copilot
adt init --tools claude,cursor

Generated configs:

.claude/instructions.md
.cursorrules
.github/copilot-instructions.md
.opencode/config.json

📈 Performance

Benchmarks

Operation	Time	Tokens
Grep (1000 files)	~2s	~50 (slim)
Complexity (100 files)	~3s	~60 (slim)
Map (large project)	~1s	~30 (slim)
Batch (10 commands)	~0.5s	~40 (slim)

System Requirements

Node.js: >= 18.0.0
OS: Windows, Linux, macOS
Memory: 512MB minimum
Disk: 50MB installed

🆚 Comparison

Feature	adt	rg + jq	ag	grep
Token-efficient output	✅	❌	❌	❌
Multi-format output	✅	❌	❌	❌
Symbol navigation	✅	❌	❌	❌
Dependency analysis	✅	❌	❌	❌
Safe editing	✅	❌	❌	❌
Git integration	✅	❌	❌	❌
AI-powered features	✅	❌	❌	❌
Cross-platform	✅	✅	✅	✅

📚 Documentation

Full Command Reference: See src/templates/commands/COMMANDS.md (94 commands documented)
Quick Start Guide: See src/templates/commands/QUICKSTART.md
Examples: See src/templates/commands/EXAMPLES.md
Full Design Spec: README_DESIGN.md
v2.0 Implementation: ADT_V2_FINAL_REPORT.md
Improvements Log: ADT_IMPROVEMENTS.md
v2.0 Plan: ADT_V2_PLAN.md

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

# Development
git clone https://github.com/byrem6/ai-dev-tools.git
cd ai-dev-tools
npm install
npm run build
npm run validate

📝 Changelog

v2.0.0 (Latest)

✨ 94 commands across 27 categories
✨ All commands now documented in templates
✨ Enhanced descriptions for all commands
✨ API, Architecture, Security, and more categories
✨ Complete command reference in templates
⚡ 5-7× token efficiency improvements
📚 Comprehensive documentation

v1.1.0

Initial stable release
60+ commands across 12 categories
Token-efficient output system

📄 License

GitHub • NPM • Issues

Built with ❤️ for AI agents and developers

⭐ Star us on GitHub — it helps!

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.adt		.adt
.claude		.claude
bin		bin
coverage		coverage
src		src
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.npmignore		.npmignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
README_DESIGN.md		README_DESIGN.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
test-cli.js		test-cli.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🤖 AI Dev Tools (adt)

📖 Overview

🎯 Perfect For

✨ Key Features

🚀 Token Efficiency

🧠 AI-Powered Intelligence

⚡ Powerful Operations

🛡️ Safety First

🚀 Quick Start

Installation

First Steps

📊 Token Efficiency Comparison

🎯 Usage Examples

For AI Agents

For Developers

AI-Powered Workflow

📚 Commands

🔍 Read & Navigation

🔎 Search & Discovery

🛠️ Editing & Refactoring

📊 Analysis & Metrics

🧠 AI Features (NEW!)

🔄 Context & Decisions (NEW!)

⚡ Batch & Automation (NEW!)

🐙 Git Operations

🧪 Quality & Testing

📝 Documentation

🌐 Additional Commands

🔧 Command Categories

💡 Pro Tips

Format Selection Guide

AI Agent Best Practices

Token Optimization

📦 API & Integration

Programmatic Usage

VS Code Integration

GitHub Actions

🎨 Output Formats

Slim Format (Token-Optimized)

Normal Format (Human-Readable)

JSON Format (Programmatic)

🛠️ Configuration

Config File Location

Default Config

🤝 AI Tool Integration

Supported Tools

📈 Performance

Benchmarks

System Requirements

🆚 Comparison

📚 Documentation

🤝 Contributing

📝 Changelog

v2.0.0 (Latest)

v1.1.0

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages