@compilr-dev/agents-coding

Coding-specific tools for @compilr-dev/agents - Git operations, project detection, smart runners, and code search.

Overview

This extension package provides tools specifically designed for building AI coding assistants. It complements the core @compilr-dev/agents library with:

• Git Tools - Structured git operations with parsed output
• Project Detection - Auto-detect project type, package manager, and tooling
• Smart Runners - Auto-detect and run tests, lint, build, format
• Code Search - Find definitions, references, and TODO comments

Installation

npm install @compilr-dev/agents-coding @compilr-dev/agents

Quick Start

import { Agent } from '@compilr-dev/agents';
import { allCodingTools } from '@compilr-dev/agents-coding';

// Create an agent with coding tools
const agent = new Agent({
  provider: yourProvider,
  tools: allCodingTools,
});

// Or register specific tools
import {
  gitStatusTool,
  gitCommitTool,
  gitBranchTool,
  detectProjectTool,
  runTestsTool,
  runLintTool,
  findDefinitionTool,
  findReferencesTool,
  findTodosTool,
} from '@compilr-dev/agents-coding';

const agent = new Agent({
  provider: yourProvider,
  tools: [gitStatusTool, detectProjectTool],
});

Available Tools

Project Detection

detectProjectTool

Detect project type and available tooling in a directory.

const result = await detectProjectTool.execute({ path: '/path/to/project' });
// Returns:
// {
//   type: 'node',
//   types: ['node'],
//   packageManager: 'pnpm',
//   testFramework: 'vitest',
//   linter: 'eslint',
//   formatter: 'prettier',
//   buildTool: 'vite',
//   configFiles: ['package.json', 'tsconfig.json'],
//   name: 'my-project'
// }

Supported Project Types:

• node - package.json
• python - pyproject.toml, setup.py, requirements.txt
• rust - Cargo.toml
• go - go.mod
• java - pom.xml, build.gradle
• ruby - Gemfile
• php - composer.json
• dotnet - *.csproj, *.sln

findProjectRootTool

Find the root directory of a project by looking for marker files.

const result = await findProjectRootTool.execute({
  path: '/path/to/project/src/components',
  markers: ['.git', 'package.json'] // optional, uses defaults
});
// Returns:
// {
//   root: '/path/to/project',
//   foundMarker: 'package.json',
//   depth: 2
// }

Git Tools

gitStatusTool

Get structured git working tree status.

const result = await gitStatusTool.execute({ path: '/path/to/repo' });
// Returns:
// {
//   branch: 'main',
//   tracking: { remote: 'origin/main', ahead: 2, behind: 0 },
//   staged: [{ path: 'src/index.ts', status: 'modified' }],
//   modified: [{ path: 'README.md', status: 'modified' }],
//   untracked: ['temp.txt'],
//   isClean: false
// }

Options:

• includeUntracked - Include untracked files (default: true)
• short - Also return short format status string

gitDiffTool

Show changes between commits, working tree, etc.

// Unstaged changes
const result = await gitDiffTool.execute({ path: '/path/to/repo' });

// Staged changes
const result = await gitDiffTool.execute({ path: '/path/to/repo', staged: true });

// Compare with a ref
const result = await gitDiffTool.execute({ path: '/path/to/repo', ref: 'HEAD~3' });

// Compare two refs
const result = await gitDiffTool.execute({
  path: '/path/to/repo',
  refA: 'main',
  refB: 'feature-branch'
});

// Returns:
// {
//   diff: '--- a/file.txt\n+++ b/file.txt\n...',
//   files: [{ path: 'file.txt', additions: 10, deletions: 3 }],
//   stats: { filesChanged: 1, insertions: 10, deletions: 3 }
// }

Options:

• staged - Show staged changes instead of unstaged
• file - Diff a specific file
• ref - Compare with a commit/branch
• refA, refB - Compare two refs
• context - Number of context lines (default: 3)
• statOnly - Show only statistics, no diff content
• nameOnly - Show only names of changed files

gitLogTool

Show commit history with filtering options.

const result = await gitLogTool.execute({
  path: '/path/to/repo',
  limit: 10,
  author: 'john',
  since: '2 weeks ago',
  grep: 'feat:'
});
// Returns:
// {
//   commits: [
//     {
//       hash: 'abc123...',
//       shortHash: 'abc123',
//       author: 'John Doe',
//       email: '[email protected]',
//       date: '2024-01-15T10:30:00Z',
//       message: 'feat: add new feature',
//       body: 'Detailed description...'
//     }
//   ]
// }

Options:

• limit - Number of commits (default: 10)
• file - Filter by file path
• author - Filter by author name/email
• since, until - Date range filters
• grep - Filter by message pattern
• ref - Branch/ref to show log for
• stat - Include diff statistics

gitCommitTool

Create a git commit with safety features.

const result = await gitCommitTool.execute({
  path: '/path/to/repo',
  message: 'feat: add new feature',
  files: ['src/index.ts', 'src/utils.ts'], // specific files to stage
  // OR
  addAll: true, // stage all including untracked
  // OR
  addModified: true, // stage only modified tracked files
});
// Returns:
// {
//   hash: 'abc123def456...',
//   shortHash: 'abc123d',
//   branch: 'main',
//   filesCommitted: 2,
//   insertions: 45,
//   deletions: 12,
//   message: 'feat: add new feature'
// }

Safety Features:

• Automatically blocks commits containing potential secrets (.env, credentials.json, .pem, etc.)
• Warns about large files (>1MB)
• Requires explicit confirmation for amend and noVerify options

Options:

• message (required) - Commit message
• files - Specific files to stage before committing
• addAll - Stage all files including untracked (git add -A)
• addModified - Stage modified/deleted tracked files only (git add -u)
• allowEmpty - Allow creating an empty commit
• amend - Amend the previous commit (dangerous)
• noVerify - Skip pre-commit hooks (dangerous)

gitBranchTool

Manage git branches.

// List all branches
const result = await gitBranchTool.execute({
  path: '/path/to/repo',
  action: 'list',
  remotes: true, // include remote branches
});
// Returns:
// {
//   current: 'main',
//   branches: [
//     { name: 'main', isCurrent: true, tracking: 'origin/main', lastCommit: 'abc123' },
//     { name: 'feature-x', isCurrent: false, tracking: 'origin/feature-x' }
//   ],
//   message: 'Found 2 branch(es)'
// }

// Create a new branch
await gitBranchTool.execute({
  path: '/path/to/repo',
  action: 'create',
  name: 'feature-y',
  startPoint: 'main', // optional base
});

// Switch branches
await gitBranchTool.execute({
  path: '/path/to/repo',
  action: 'switch',
  name: 'feature-y',
});

// Delete a branch
await gitBranchTool.execute({
  path: '/path/to/repo',
  action: 'delete',
  name: 'feature-y',
  force: true, // delete even if not merged
});

// Rename a branch
await gitBranchTool.execute({
  path: '/path/to/repo',
  action: 'rename',
  name: 'old-name',
  newName: 'new-name',
});

Actions:

• list - Show all branches
• create - Create a new branch
• delete - Delete a branch (protects current branch)
• switch - Switch to a branch
• rename - Rename a branch

gitStashTool

Manage git stashes.

// Stash current changes
const result = await gitStashTool.execute({
  path: '/path/to/repo',
  action: 'push',
  message: 'WIP: feature work',
  includeUntracked: true,
});
// Returns:
// { message: 'Stashed changes: WIP: feature work' }

// List all stashes
const result = await gitStashTool.execute({
  path: '/path/to/repo',
  action: 'list',
});
// Returns:
// {
//   stashes: [
//     { ref: 'stash@{0}', index: 0, branch: 'main', message: 'WIP: feature work' },
//     { ref: 'stash@{1}', index: 1, branch: 'main', message: 'backup' }
//   ],
//   message: 'Found 2 stash(es)'
// }

// Pop stash (apply and remove)
await gitStashTool.execute({
  path: '/path/to/repo',
  action: 'pop',
  index: 0, // optional, defaults to 0
});

// Apply stash (keep in stash list)
await gitStashTool.execute({
  path: '/path/to/repo',
  action: 'apply',
  index: 0,
});

// Show stash contents
const result = await gitStashTool.execute({
  path: '/path/to/repo',
  action: 'show',
  index: 0,
});
// Returns:
// { diff: '--- a/file.txt\n...', message: ' file.txt | 5 ++---\n 1 file changed...' }

// Drop a specific stash
await gitStashTool.execute({
  path: '/path/to/repo',
  action: 'drop',
  index: 1,
});

// Clear all stashes
await gitStashTool.execute({
  path: '/path/to/repo',
  action: 'clear',
});

Actions:

• push - Save changes to stash
• pop - Apply and remove stash
• apply - Apply stash without removing
• list - Show all stashes
• drop - Remove a specific stash
• clear - Remove all stashes
• show - Display stash contents

Smart Runner Tools

All runner tools support a dryRun option to detect the tool/framework and return the command without actually executing it. This is useful for:

• Previewing what command would run
• Testing detection logic without side effects
• Implementing "rehearsal" patterns for safety

// Dry run - just detect, don't execute
const result = await runBuildTool.execute({
  path: '/path/to/project',
  dryRun: true,
});
// Returns detected tool and command without running it:
// { buildTool: 'vite', command: 'npx vite build', output: '(dry run - command not executed)' }

runTestsTool

Auto-detect and run tests using the appropriate test framework.

const result = await runTestsTool.execute({
  path: '/path/to/project',
  pattern: 'src/**/*.test.ts', // optional filter
  coverage: true,
  verbose: true,
});
// Returns:
// {
//   command: 'npx vitest run --coverage',
//   output: '...',
//   exitCode: 0,
//   duration: 5230,
//   success: true,
//   framework: 'vitest',
//   passed: 42,
//   failed: 0,
//   total: 42
// }

Supported Frameworks:

• vitest - vitest.config.ts/js or dependency
• jest - jest.config.ts/js/json or dependency
• mocha - .mocharc.json/js/yaml or dependency
• ava - ava.config.js/cjs or dependency
• npm test - package.json scripts.test
• pytest - pytest.ini, pyproject.toml, conftest.py
• unittest - setup.py, setup.cfg
• cargo test - Cargo.toml
• go test - go.mod

Options:

• pattern - Test file pattern or name filter
• watch - Run in watch mode
• coverage - Generate coverage report
• verbose - Verbose output
• updateSnapshots - Update test snapshots (jest/vitest)
• timeout - Command timeout in milliseconds

runLintTool

Auto-detect and run linter.

const result = await runLintTool.execute({
  path: '/path/to/project',
  fix: true,
  files: ['src/index.ts'],
});
// Returns:
// {
//   command: 'npx eslint src/index.ts --fix',
//   output: '...',
//   exitCode: 0,
//   duration: 1230,
//   success: true,
//   linter: 'eslint',
//   errors: 0,
//   warnings: 2
// }

Supported Linters:

• eslint - eslint.config.js/mjs/cjs, .eslintrc.* or dependency
• biome - biome.json/jsonc or dependency
• npm lint - package.json scripts.lint
• ruff - ruff.toml, .ruff.toml
• pylint - .pylintrc, pylintrc
• flake8 - .flake8, setup.cfg
• clippy - Cargo.toml
• golangci-lint - .golangci.yml/yaml/json or go.mod

Options:

• files - Specific files to lint
• fix - Auto-fix issues
• format - Output format (json, stylish, etc.)
• timeout - Command timeout

runBuildTool

Auto-detect and run build.

const result = await runBuildTool.execute({
  path: '/path/to/project',
  production: true,
});
// Returns:
// {
//   command: 'npx vite build --mode production',
//   output: '...',
//   exitCode: 0,
//   duration: 8500,
//   success: true,
//   buildTool: 'vite'
// }

Supported Build Tools:

• vite - vite.config.ts/js/mjs or dependency
• next - next.config.js/mjs/ts or dependency
• tsc - tsconfig.json with typescript dependency
• webpack - webpack.config.js/ts or dependency
• rollup - rollup.config.js/mjs or dependency
• esbuild - esbuild.config.js/mjs or dependency
• turbo - turbo.json or dependency
• npm build - package.json scripts.build
• cargo build - Cargo.toml
• go build - go.mod
• python build - setup.py, pyproject.toml
• maven - pom.xml
• gradle - build.gradle, build.gradle.kts

Options:

• production - Build for production
• clean - Clean before build
• timeout - Command timeout

runFormatTool

Auto-detect and run formatter.

const result = await runFormatTool.execute({
  path: '/path/to/project',
  check: true, // check only, don't write
});
// Returns:
// {
//   command: 'npx prettier --check .',
//   output: '...',
//   exitCode: 0,
//   duration: 2100,
//   success: true,
//   formatter: 'prettier',
//   filesProcessed: 45
// }

Supported Formatters:

• prettier - .prettierrc.* or prettier.config.* or dependency
• biome - biome.json/jsonc or dependency
• dprint - dprint.json, .dprint.json or dependency
• npm format - package.json scripts.format
• black - pyproject.toml, .black
• ruff format - ruff.toml, .ruff.toml
• autopep8 - .pep8, setup.cfg
• rustfmt - Cargo.toml
• gofmt - go.mod
• goimports - go.mod

Options:

• files - Specific files to format
• check - Check only, don't write changes
• timeout - Command timeout

Code Search Tools

findDefinitionTool

Find where a symbol is defined in the codebase.

const result = await findDefinitionTool.execute({
  path: '/path/to/project',
  symbol: 'calculateSum',
  fileType: 'ts', // optional filter
});
// Returns:
// {
//   definitions: [
//     {
//       file: 'src/utils.ts',
//       line: 8,
//       column: 17,
//       context: 'export function calculateSum(a: number, b: number): number {',
//       type: 'function',
//       isExported: true
//     }
//   ],
//   totalFound: 1,
//   symbol: 'calculateSum'
// }

Supported Languages:

• TypeScript/JavaScript - functions, classes, interfaces, types, const, enums
• Python - functions, classes, async functions
• Rust - fn, struct, enum, trait, type
• Go - func, type, const, var
• Java/Kotlin - classes, interfaces, methods

Options:

• symbol (required) - Symbol name to find
• path - Working directory
• fileType - File type filter (ts, py, rs, go, java, etc.)
• limit - Maximum results (default: 20)

findReferencesTool

Find all usages of a symbol in the codebase.

const result = await findReferencesTool.execute({
  path: '/path/to/project',
  symbol: 'calculateSum',
  excludeDefinitions: true,
});
// Returns:
// {
//   references: [
//     { file: 'src/main.ts', line: 5, column: 18, context: '  const sum = calculateSum(1, 2);' },
//     { file: 'src/calc.ts', line: 12, column: 10, context: '  return calculateSum(a, b);' }
//   ],
//   totalFound: 2,
//   symbol: 'calculateSum'
// }

Options:

• symbol (required) - Symbol name to find
• path - Working directory
• fileType - File type filter
• excludeDefinitions - Exclude definition lines, show only usages (default: false)
• limit - Maximum results (default: 50)

findTodosTool

Find TODO, FIXME, HACK, and other comment markers in code.

const result = await findTodosTool.execute({
  path: '/path/to/project',
  types: ['TODO', 'FIXME'],
  includeAuthor: true,
});
// Returns:
// {
//   todos: [
//     {
//       type: 'TODO',
//       file: 'src/utils.ts',
//       line: 5,
//       text: 'Add error handling',
//       author: 'John Doe' // if includeAuthor: true
//     },
//     {
//       type: 'FIXME',
//       file: 'src/api.ts',
//       line: 42,
//       text: 'This needs optimization'
//     }
//   ],
//   summary: { TODO: 1, FIXME: 1 },
//   totalFound: 2
// }

Supported Comment Types:

• TODO - Tasks to be done
• FIXME - Bugs to fix
• HACK - Workarounds
• XXX - Critical issues
• NOTE - Important notes
• BUG - Known bugs
• WARN - Warnings

Options:

• path - Working directory
• types - Comment types to find (default: all)
• fileType - File type filter (ts, py, rs, go, etc.)
• includeAuthor - Include git blame author info (slower, limited to first 20 results)
• limit - Maximum results (default: 100)

Factory Functions

Each tool has a factory function for customization:

import { createGitStatusTool, createDetectProjectTool } from '@compilr-dev/agents-coding';

// Custom base directory
const customGitStatus = createGitStatusTool({
  baseDir: '/workspace',
  defaultIncludeUntracked: false,
});

const customDetectProject = createDetectProjectTool({
  baseDir: '/workspace',
});

Design Principles

1. Zero Dependencies - Only peer dependency on @compilr-dev/agents
2. Structured Output - All tools return parsed, typed data (not raw strings)
3. CLI-First - Uses git CLI directly for predictable behavior
4. Safety First - Git tools include protections against dangerous operations
5. TypeScript Native - Full type safety throughout

Roadmap

Phase 1: Foundation ✅

• [x] detectProjectTool
• [x] findProjectRootTool
• [x] gitStatusTool
• [x] gitDiffTool
• [x] gitLogTool

Phase 2: Core Git ✅

• [x] gitCommitTool - Create commits with safety features
• [x] gitBranchTool - Branch management
• [x] gitStashTool - Stash operations

Phase 3: Smart Runners ✅

• [x] runTestsTool - Auto-detect and run tests
• [x] runLintTool - Auto-detect and run linter
• [x] runBuildTool - Auto-detect and run build
• [x] runFormatTool - Auto-detect and run formatter

Phase 4: Code Search ✅

• [x] findDefinitionTool - Find symbol definitions
• [x] findReferencesTool - Find symbol usages
• [x] findTodosTool - Find TODO/FIXME comments

Phase 5: Skills & Polish ✅

• [x] Coding-specific skills (6 skills)
• [x] Comprehensive documentation

Skills

Coding-specific skills for specialized workflows. Use with SkillRegistry from @compilr-dev/agents.

import { SkillRegistry } from '@compilr-dev/agents';
import { codingSkills } from '@compilr-dev/agents-coding';

const registry = new SkillRegistry();
registry.registerAll(codingSkills);

// Invoke a skill
const result = registry.invoke('git-workflow');
console.log(result.prompt); // Expanded skill prompt

Available Skills

| Skill | Description | |-------|-------------| | git-workflow | Best practices for git operations with safety checks | | test-driven | Test-driven development workflow with smart runners | | code-navigation | Effectively navigate and understand codebases | | pr-workflow | Pull request creation and review workflow | | project-onboarding | Quickly understand and navigate a new project | | code-optimization | Performance optimization workflow |

Skill Details

git-workflow

Safe git operations including verification before destructive actions, commit workflow, and recovery strategies.

test-driven

Red-Green-Refactor cycle with integration of runTests, runLint, runBuild, and runFormat tools.

code-navigation

Using findDefinition, findReferences, and findTodos to understand and navigate code.

pr-workflow

Complete PR workflow from branch preparation through review and merge, with pre-flight checks.

project-onboarding

Systematic approach to understanding new codebases using detectProject and search tools.

code-optimization

Performance optimization with measurement-first approach and common optimization patterns.

Runtime Dependencies

Some tools require external programs to be installed:

| Tool | Dependency | Installation | |------|------------|--------------| | Code Search tools | ripgrep (rg) | apt install ripgrep or brew install ripgrep | | Git tools | git | Usually pre-installed |

License

MIT

Related

• @compilr-dev/agents - Core agent library