cats 0.1.2

# AGENTS.md

This file provides guidance to AI coding agents when working with the CATS (Coding Agent ToolS) crate.

## Project Overview

CATS is a Rust library that provides a comprehensive toolkit for building AI-powered coding agents. It offers structured, LLM-friendly tools for file manipulation, code editing, search, and execution. The crate is published on crates.io and designed to be used as a library dependency or standalone CLI tool.

## Setup Commands

```bash
# Install dependencies
cargo build

# Run tests
cargo test

# Run tests with optional tiktoken feature
cargo test --all-features

# Build CLI binary
cargo build --bin cats

# Build and run CLI
cargo run --bin cats -- --help

# Build for release
cargo build --release

# Run specific test
cargo test <test_name>

# Check formatting
cargo fmt --check

# Run linter
cargo clippy -- -D warnings
```

## Code Style

- **Rust Edition**: 2021
- **Formatting**: Standard `rustfmt` configuration
- **Linting**: Pass all clippy warnings
- **Error Handling**: Use `anyhow::Result` for tool execution, `thiserror` for custom error types
- **Async**: Use Tokio runtime where needed
- **Documentation**: All public APIs must have rustdoc comments with examples

## Architecture

### Core Components

1. **Tool Registry** (`src/core.rs`)
   - Central registry for all tools
   - Tool validation and execution
   - Shared state management via `Arc<Mutex<ToolState>>`

2. **Tool Categories**
   - File Navigation (`src/file_navigation/mod.rs`)
   - Search (`src/search/mod.rs`)
   - Editing (`src/editing/mod.rs`)
   - Execution (`src/execution.rs`)
   - State (`src/state/mod.rs`)
   - Utils (`src/utils/mod.rs`)

3. **CLI Binary** (`src/main.rs`)
   - Uses `clap` for argument parsing
   - Dynamically generates subcommands from tool registry
   - Tools are listed and described automatically from `create_tool_registry()`

### Key Design Patterns

- **Trait-based Tools**: All tools implement the `Tool` trait
- **Windowed File Viewing**: Files are shown in configurable line windows (default 50 lines)
- **Stateful Navigation**: File positions and states are tracked across tool calls
- **Safe Command Execution**: Commands are validated and executed with timeouts
- **LLM-friendly Output**: All tool results include structured messages for language models

## Testing Instructions

- Run full test suite: `cargo test`
- Tests are organized by module (inline `mod tests`)
- Use `tempfile` crate for isolated test environments
- All tests must pass before committing
- Integration tests for tools in `src/*/tests.rs`
- CLI tests use `assert_cmd` and `predicates` crates

### Test Coverage

Ensure tests cover:
- Tool registration and execution
- Argument validation
- Error handling
- Edge cases (empty files, large files, etc.)
- State management across multiple tool calls

## Important Notes for Agents

### Tool System

- **Dynamic Tool Listing**: The CLI (`src/main.rs`) dynamically lists all tools from the registry
- **Never hardcode tool names**: Always use `registry.list_tools()` and `registry.get_tool()`
- **Tool descriptions**: Pulled directly from each tool's `description()` method

### Version Management

- **Public Crate**: CATS is published on crates.io - use semantic versioning carefully
- **Breaking Changes**: Major version bump (e.g., 0.1.x → 0.2.0)
- **New Features**: Minor version bump (e.g., 0.1.0 → 0.2.0 in 0.x versions)
- **Bug Fixes**: Patch version bump (e.g., 0.1.0 → 0.1.1)
- **Update CHANGELOG.md**: Always document changes in CHANGELOG.md

### Publishing to crates.io

```bash
# Verify package contents
cargo package --list

# Dry run (test publish without uploading)
cargo publish --dry-run

# Publish to crates.io (requires authentication)
cargo publish
```

### Adding New Tools

1. Implement the `Tool` trait
2. Add tool to appropriate module (file_navigation, editing, etc.)
3. Register in `create_tool_registry()` function in `src/lib.rs`
4. Add tests for the new tool
5. Update README.md with tool documentation
6. CLI will automatically pick up the new tool

### File Structure

```
cats/
├── Cargo.toml              # Package manifest with crates.io metadata
├── README.md               # Human-readable documentation
├── CHANGELOG.md            # Version history
├── LICENSE-MIT             # MIT license
├── LICENSE-APACHE          # Apache 2.0 license
├── src/
│   ├── lib.rs              # Library entry point, tool registry creation
│   ├── main.rs             # CLI binary
│   ├── core.rs             # Tool trait, registry, core types
│   ├── execution.rs        # Command execution tool
│   ├── file_navigation/    # File viewing and navigation tools
│   ├── search/             # File and content search tools
│   ├── editing/            # Text editing and file management tools
│   ├── state/              # State management
│   ├── linting/            # Code linting utilities
│   └── utils/              # Utility tools (tokens, filemap, etc.)
└── target/                 # Build artifacts (gitignored)
```

## Commit Guidelines

- Use conventional commits format: `type(scope): description`
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
- Examples:
  - `feat(tools): add new file_diff tool`
  - `fix(cli): dynamically list tools from registry`
  - `docs(readme): update installation instructions`
  - `test(editing): add tests for delete_function tool`

## Dependencies

### Core Dependencies
- `anyhow` - Error handling
- `serde`, `serde_json` - Serialization
- `regex` - Pattern matching
- `glob`, `walkdir` - File system operations
- `tokio` - Async runtime
- `clap` - CLI argument parsing
- `thiserror` - Custom error types
- `tracing` - Logging
- `tempfile` - Temporary files for tests
- `edit-distance` - String similarity
- `toml` - Configuration parsing
- `syn` - Rust code parsing (for linting)

### Optional Dependencies
- `tiktoken-rs` - Token counting (feature-gated as "tiktoken")

## Security Considerations

- **Command Execution**: The `run_command` tool filters dangerous commands
- **File Operations**: Validate paths to prevent directory traversal
- **Timeout Protection**: All command executions have configurable timeouts
- **No Arbitrary Code Execution**: Tools are structured and validated

## Common Pitfalls

1. **Don't hardcode tool lists**: Use `registry.list_tools()` instead
2. **State lifetime**: Tools share state via `Arc<Mutex<ToolState>>`
3. **CLI lifetimes**: Clap requires `'static` strings - use `Box::leak()` for dynamic content
4. **Test isolation**: Always use `tempfile` for file system tests
5. **Error context**: Provide helpful error messages for LLMs to understand failures

## Integration with Simpaticoder

CATS was extracted from the Simpaticoder project and is now maintained as an independent crate. Changes here may affect Simpaticoder's tool system. Coordinate breaking changes carefully.