🤖 AI AGENT TOOLKIT

🚀 Suite of 5 AI-powered CLI agents for automating software development workflows.

🎬 Demo · ⚡ Quick Start · 📦 Installation · 🤖 Agents · 🧠 Providers · ⚙️ CLI Flags · 🤝 Contributing

---

📋 Overview

AI Agent Toolkit is a monorepo grouping 5 independent AI agents, each specialized in a different development task. They share a unified CLI, common stack, and support multiple AI providers.

npx @aiagentkit/ai-agent-toolkit doc       ./src   # 📄 automatic documentation
npx @aiagentkit/ai-agent-toolkit test      ./src   # 🧪 unit tests
npx @aiagentkit/ai-agent-toolkit review    ./src   # 🔍 code review
npx @aiagentkit/ai-agent-toolkit refactor  ./src   # ♻️ refactoring
npx @aiagentkit/ai-agent-toolkit audit     ./src   # 🛡️ security audit

---

🎬 See it in action

One command turns an undocumented file into documented code — here with a local Ollama model, no API key needed:

$ npx @aiagentkit/ai-agent-toolkit doc --path ./src --provider ollama
=== Agent Doc Generator v2.1.0 ===
✔ Provider: ollama | Model: qwen2.5-coder:1.5b
✔ Found 1 file(s) to process.
✔ [1/1] src/userService.ts → [DOC]
✔ Documentation generated: DOCS.md

Before — userService.ts without docs:

export class UserService {
  private users: User[] = [];

  addUser(name: string, email: string): User {
    const user: User = { id: this.users.length + 1, name, email };
    this.users.push(user);
    return user;
  }
}

After — DOCS.md, generated automatically:

/**
 * Adds a new user to the service.
 *
 * @param {string} name - The name of the user.
 * @param {string} email - The email address of the user.
 * @returns {User} The added user object.
 */
addUser(name: string, email: string): User {
  const user: User = { id: this.users.length + 1, name, email };
  this.users.push(user);
  return user;
}

---

🤖 Agents

Command	Package	Version	Description
ai-toolkit doc	@aiagentkit/agent-doc-generator	v1.0.1	📄 Generates JSDoc documentation automatically
ai-toolkit test	@aiagentkit/agent-test-generator	v1.0.1	🧪 Generates unit tests with Vitest
ai-toolkit review	@aiagentkit/agent-code-review	v1.0.1	🔍 Analyzes code quality and cyclomatic complexity
ai-toolkit refactor	@aiagentkit/agent-refactor	v1.0.1	♻️ Suggests and applies refactorizations with diffs
ai-toolkit audit	@aiagentkit/agent-security-audit	v1.0.1	🛡️ OWASP Top 10 security audit

💡 Each agent is an independent npm package. Install them separately or use the unified CLI.

---

🧠 Supported AI Providers

Supports 5 providers with automatic detection. If you don't specify --provider, the toolkit detects what you have configured.

Provider	Default Model	Auth	Notes
🔷 Gemini	gemini-2.5-flash	GEMINI_API_KEY	Free tier available
🟢 OpenAI	gpt-4o	OPENAI_API_KEY	GPT-4o, GPT-4o-mini
🟠 Anthropic	claude-sonnet-4-20250514	ANTHROPIC_API_KEY	Best for coding
🔵 DeepSeek	deepseek-chat	DEEPSEEK_API_KEY	Most affordable
🦙 Ollama	local model	No key	Local, free, full privacy

🔍 Detection priority: OpenAI > Anthropic > DeepSeek > Gemini > Ollama

# 🎯 Specify provider explicitly
npx @aiagentkit/ai-agent-toolkit doc --path ./src --provider openai
npx @aiagentkit/ai-agent-toolkit audit --path ./src --provider ollama --model qwen3.5:9b

---

📦 Installation

🚀 From npm (published)

npm install -g @aiagentkit/ai-agent-toolkit
npx @aiagentkit/ai-agent-toolkit doc --path ./src

Or install agents individually:

npx @aiagentkit/agent-doc-generator --path ./src
npx @aiagentkit/agent-test-generator --path ./src

📥 From repository

git clone https://github.com/MarceloAdan73/ai-agent-toolkit.git
cd ai-agent-toolkit
npm install && npm run build

# ⚙️ Configure a provider (API keys are read from .env)
echo "GEMINI_API_KEY=your_key" > .env
# Or set any of: OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY

# ▶️ Run
node toolkit/dist/cli.js doc --path ./src

---

⚡ Quick Start

The problem: you have a legacy repo with 50 undocumented files and no time to write JSDoc by hand (~4 hours of work).

The fix: one command.

# 1. Install the toolkit once
npm install -g @aiagentkit/ai-agent-toolkit

# 2. Document your whole src/ folder (auto-detects provider, or set one)
npx @aiagentkit/ai-agent-toolkit doc --path ./src

# 3. Get a single DOCS.md with every public API documented

💡 Try it locally with no API key at all: install Ollama, pull a model (ollama pull qwen2.5-coder:1.5b), and run with --provider ollama.

---

🏗️ Architecture

ai-agent-toolkit/
├── package.json                 # 📦 npm workspaces
├── toolkit/                     # 🖥️ Unified CLI (ai-toolkit)
│   └── src/cli.ts
├── agent-doc-generator/         # 📄 documentation
├── agent-test-generator/        # 🧪 unit tests
├── agent-code-review/           # 🔍 code review
├── agent-refactor/              # ♻️ refactoring
└── agent-security-audit/        # 🛡️ OWASP security audit

Each agent contains: src/ (logic), tests/ (Vitest), index.ts (entry point), package.json (bin, files, engines).

---

🛠️ Tech Stack

Layer	Technology
💻 Language	TypeScript (strict mode)
⚡ Runtime	Node.js >= 18 (ES Modules)
🧠 AI Providers	Gemini, OpenAI, Anthropic, DeepSeek, Ollama
🖥️ CLI	Commander.js
⏳ Progress UI	ora
🧪 Testing	Vitest (626 tests)
🔄 CI/CD	GitHub Actions
📦 Bundling	tsc (TypeScript compiler)

---

⚙️ CLI Flags

Flag	Description	Default
--path	📁 File or folder to process	(required)
--provider	🧠 gemini | openai | anthropic | deepseek | ollama	auto-detected
--model	🤖 Model to use	per provider
--base-url	🌐 Server URL (Ollama)	http://localhost:11434
--api-key	🔑 API key (optional for Ollama)	.env
--max-chars	📏 Character limit per file	15000
--output	📂 Output folder/file	next to source
--extensions	📎 Extensions to process (CSV)	all
--split	📑 One file per source	false
--format	📄 terminal | markdown | html | pdf	terminal
--severity	⚠️ Minimum severity (audit)	info
--dry-run	👁️ Preview only, don't write	false
--verbose	📝 Detailed logs	false

---

✨ Features

Feature	Description
🧠 Multi-provider	5 AI providers with auto-detection
💾 Smart cache	MD5 hash, skips unchanged files
🔄 Resilience	3 retries with backoff on API errors
✂️ Safe truncation	Large files trimmed with warning
📎 Extension filter	--extensions .ts,.prisma to limit scope
📄 Export	Terminal, Markdown, HTML or PDF
👁️ Dry-run	Preview before writing changes
📑 Split mode	One output file per analyzed source

---

📜 Scripts

npm run build            # 🏗️ build all packages
npm run test             # 🧪 626 tests
npm run typecheck        # 🔍 strict typecheck
npm run test:integration # 🔗 tests with real providers (requires API keys)

---

🗺️ Roadmap

• ✅ 5 functional agents with 626 tests
• ✅ Unified CLI ai-toolkit
• ✅ Multi-provider + auto-detection
• ✅ Response caching
• ✅ HTML/PDF export
• ✅ CI/CD with GitHub Actions
• ✅ Ready for npm publishing
• ✅ Publish to npm
• ⏳ Integration tests with real providers
• ⏳ Configuration via .rc files

---

🤝 Contributing

Contributions are welcome! Open an issue or a PR.

# 1. 🍴 Fork
# 2. 🔀 Create branch
git checkout -b feature/new-feature

# 3. 💾 Commit
git commit -m 'Add new feature'

# 4. 📤 Push
git push origin feature/new-feature

# 5. 🔁 Pull Request

---

📄 License

MIT — 🧑‍💻 Marcelo Adan

---

🐙 GitHub · 🐛 Report Bug · 💡 Request Feature