Package Exports

@compilr-dev/agents-coding
@compilr-dev/agents-coding/skills
@compilr-dev/agents-coding/tools/git
@compilr-dev/agents-coding/tools/project
@compilr-dev/agents-coding/tools/runners
@compilr-dev/agents-coding/tools/search

Readme

@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: 'john@example.com',
//       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

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

Roadmap

Phase 1: Foundation ✅

detectProjectTool
findProjectRootTool
gitStatusTool
gitDiffTool
gitLogTool

Phase 2: Core Git ✅

gitCommitTool - Create commits with safety features
gitBranchTool - Branch management
gitStashTool - Stash operations

Phase 3: Smart Runners ✅

runTestsTool - Auto-detect and run tests
runLintTool - Auto-detect and run linter
runBuildTool - Auto-detect and run build
runFormatTool - Auto-detect and run formatter

Phase 4: Code Search ✅

findDefinitionTool - Find symbol definitions
findReferencesTool - Find symbol usages
findTodosTool - Find TODO/FIXME comments

Phase 5: Skills & Polish ✅

Coding-specific skills (6 skills)
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

@compilr-dev/agents - Core agent library