CATS - Coding Agent ToolS

A comprehensive toolkit for building AI-powered coding agents. CATS provides structured, LLM-friendly tools for file manipulation, code editing, search, and execution that work seamlessly with language models.

Features

• 🔍 File Navigation: Windowed file viewing with line-by-line navigation and scrolling
• 🔎 Search Tools: Fast file discovery and content search across files and directories
• ✏️ Code Editing: Intelligent text editing with search/replace, insert, delete operations
• 📂 File Management: Create, move, copy, and delete files and directories
• ⚡ Command Execution: Safe command execution with timeout and validation
• 📊 State Management: Persistent tool state and session history
• 🗺️ Project Mapping: Visualize project structure with intelligent elision
• 🎯 Task Classification: Built-in task classification for agent workflows

Quick Start

Add CATS to your Cargo.toml:

[dependencies]
cats = "0.1.0"

Basic Usage

use cats::{create_tool_registry, ToolArgs};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create the tool registry
    let mut registry = create_tool_registry();
    
    // Execute a tool
    let args = ToolArgs::from_args(&["src/main.rs"]);
    let result = registry.execute_tool("open", &args)?;
    
    println!("{}", result.message);
    Ok(())
}

With Custom Window Size

use cats::create_tool_registry_with_open_window_size;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create registry with custom window size for file viewing
    let mut registry = create_tool_registry_with_open_window_size(50);
    
    // Now 'open' tool will show 50 lines at a time
    Ok(())
}

Available Tools

File Navigation

• open - Opens a file and displays a window of lines
• goto - Jumps to a specific line number in the current file
• scroll_up - Scrolls the viewing window up
• scroll_down - Scrolls the viewing window down

Search

• find_file - Search for files by name pattern
• search_file - Search for text within a specific file
• search_dir - Search for text across all files in a directory

Editing

• create_file - Create a new file with content
• replace_text - Replace text using search/replace pattern
• insert_text - Insert text at a specific line
• delete_text - Delete a range of lines
• delete_line - Delete a specific line
• overwrite_file - Replace entire file contents
• delete_function - Delete a Rust function by name (Rust-aware)

File Management

• delete_path - Delete a file or directory
• move_path - Move or rename a file/directory
• copy_path - Copy a file or directory
• create_directory - Create a new directory

Execution

• run_command - Execute shell commands with timeout and validation

Utilities

• _state - Display current tool state and context
• count_tokens - Count tokens in a file (requires tiktoken feature)
• filemap - Generate a project structure visualization
• submit - Mark task as complete
• classify_task - Classify task type for workflow routing

Tool Execution Patterns

Using Named Arguments (Recommended for LLMs)

use cats::{create_tool_registry, ToolArgs};
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut registry = create_tool_registry();
    
    // LLMs typically provide JSON with named parameters
    let mut args = HashMap::new();
    args.insert("file_path".to_string(), "src/main.rs".to_string());
    args.insert("insert_line".to_string(), "10".to_string());
    args.insert("new_str".to_string(), "// New comment".to_string());
    
    let tool_args = ToolArgs::from_named(args);
    let result = registry.execute_tool("insert_text", &tool_args)?;
    
    println!("{}", result.message);
    Ok(())
}

Using Positional Arguments

use cats::{create_tool_registry, ToolArgs};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut registry = create_tool_registry();
    
    let args = ToolArgs::from_args(&["src", "TODO"]);
    let result = registry.execute_tool("search_dir", &args)?;
    
    println!("{}", result.message);
    Ok(())
}

Features Flags

tiktoken (Optional)

Enable token counting functionality using the cl100k_base tokenizer:

[dependencies]
cats = { version = "0.1.0", features = ["tiktoken"] }

With this feature enabled, you can use the count_tokens tool:

use cats::{create_tool_registry, ToolArgs};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut registry = create_tool_registry();
    let args = ToolArgs::from_args(&["src/main.rs"]);
    let result = registry.execute_tool("count_tokens", &args)?;
    println!("{}", result.message);  // "Total tokens: 1234"
    Ok(())
}

Architecture

CATS is designed with LLM integration as a first-class concern:

• Structured Outputs: All tools return structured ToolResult types with clear success/error states
• Schema Generation: Tools provide JSON schemas for LLM function calling
• Error Handling: Comprehensive error messages with suggestions for resolution
• State Tracking: Maintains context about open files and operations
• Token Awareness: Optional token counting for context management

Integration Examples

With OpenAI Function Calling

use cats::create_tool_registry;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let registry = create_tool_registry();
    
    // Get all tool schemas for OpenAI function calling
    let schemas = registry.get_all_schemas();
    
    // Send schemas to OpenAI API as available functions
    // ... your OpenAI integration code ...
    
    Ok(())
}

As a CLI Tool

CATS includes a binary that can be used standalone:

# Install the CLI
cargo install cats

# Use tools from command line
cats open src/main.rs
cats search_dir . "TODO"
cats filemap src/

Platform Support

• Linux (x86_64, aarch64) - Tier 1 (fully supported and tested)
• macOS (x86_64, aarch64) - Tier 2 (builds and tests pass)
• Windows (x86_64) - Tier 3 (best-effort support)

Migration from simpaticoder-tools

CATS is the successor to simpaticoder-tools. The crate has been renamed and extracted for independent use:

# Old (deprecated)
[dependencies]
simpaticoder-tools = "0.1.0"

# New
[dependencies]
cats = "0.1.0"

Update imports:

// Old
use simpaticoder_tools::{create_tool_registry, ToolArgs};

// New  
use cats::{create_tool_registry, ToolArgs};

The API surface remains identical - only the crate name has changed.

Documentation

• API Documentation
• Examples
• Homepage

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Acknowledgments

CATS is inspired by and builds upon concepts from:

• SWE-agent - Agent-Computer Interface design
• The broader AI coding agent community

---

Built for the future of AI-assisted software development. 🚀