clacky 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9c76e82a2f70e2bb34e98a8c81b7cf9a7c6f561d3218e32c44b4191160614279
+  data.tar.gz: b5aa7eb4906ac3737c58e17a9c64763dbf287c2b453b7dcc8d4db0ac64c6a241
+SHA512:
+  metadata.gz: 06c9e6dcff8dd3033145fa7945820870432265ce00cbe32728e09fccc99b698c7c7431f9cf8a887c1f249c1538f6fbfbc0e10d5a506b5d89652daa315c9ae053
+  data.tar.gz: d374692b73182a5c844a3a1c528a5677bcba751063afe6b2604b037314afd6e4bfc9ef1121ebdc30acb49336a0a914b3035f46d705ad0816ef1a32371436c175

data/.clackyrules

@@ -0,0 +1,80 @@
+# Clacky Project Rules (.clackyrules)
+
+## Project Overview
+This is the `clacky` Ruby gem - a command-line interface for interacting with AI models (Claude, OpenAI, etc.).
+It provides chat functionality and autonomous AI agent capabilities with tool use.
+
+## Project Structure
+- `lib/clacky/` - Main gem source code
+  - `cli.rb` - Command-line interface using Thor
+  - `agent.rb` - Core AI agent with tool execution
+  - `tools/` - Built-in tools (file operations, web search, shell, etc.)
+  - `client.rb` - API client for AI models
+  - `config.rb` - Configuration management
+- `bin/` - Development executables
+- `spec/` - RSpec test suite
+- `clacky.gemspec` - Gem specification
+
+## Development Guidelines
+
+### Code Style
+- Follow Ruby conventions and best practices
+- Use frozen string literals: `# frozen_string_literal: true`
+- Keep classes focused and single-responsibility
+- Use meaningful variable and method names
+- Add descriptive comments for complex logic
+
+### Architecture Patterns
+- Tools inherit from `Clacky::Tools::Base`
+- Each tool defines: `tool_name`, `tool_description`, `tool_category`, `tool_parameters`
+- Agent uses React pattern (Reason-Act-Observe) for task execution
+- Configuration is managed through `Clacky::Config`
+- CLI commands use Thor framework
+
+### Testing
+- Use RSpec for testing
+- Test files in `spec/` directory
+- **IMPORTANT**: Always run `bundle exec rspec` to verify tests pass after making changes
+- All tests must pass before considering a task complete
+- Maintain good test coverage
+- When modifying existing functionality, ensure related tests still pass
+- When adding new features, consider adding corresponding tests
+
+### Tool Development
+When adding new tools:
+1. Create class in `lib/clacky/tools/`
+2. Inherit from `Clacky::Tools::Base`
+3. Define required class attributes
+4. Implement `execute` method
+5. Add optional `format_call` and `format_result` methods
+6. Require in `lib/clacky.rb`
+
+### Agent Behavior
+- TODO manager is for planning only - must execute tasks after planning
+- Always use tools to create/modify files, don't just return code
+- Maintain conversation context across tasks
+- Follow cost and iteration limits
+- Support different permission modes (confirm_all, confirm_edits, auto_approve, plan_only)
+
+## Dependencies
+- Ruby >= 3.1.0
+- faraday (~> 2.0) - HTTP client
+- thor (~> 1.3) - CLI framework
+- tty-prompt (~> 0.23) - Interactive prompts
+- tty-spinner (~> 0.9) - Progress indicators
+- diffy (~> 3.4) - Text diffs
+
+## Important Notes
+- This gem is designed to work with OpenAI-compatible APIs
+- Security features include safe shell execution and path validation
+- Agent includes cost control and message compression features
+- Built-in tools cover file operations, web search, code execution, and project management
+
+## Execution Binary
+- Development: `bin/clacky` (in repository)
+- Installed gem: `clacky` command globally available
+
+## Configuration
+- Stores API keys and settings in user's home directory
+- Supports multiple AI model providers
+- Configurable through `clacky config set` command

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.5.0] - 2026-01-11
+
+### Added
+- **Agent Mode**: Autonomous AI agent with tool execution capabilities
+- **Built-in Tools**: 
+  - `safe_shell` - Safe shell command execution with security checks
+  - `file_reader` - Read file contents
+  - `write` - Create/overwrite files with diff preview
+  - `edit` - Precise file editing with string replacement
+  - `glob` - Find files using glob patterns
+  - `grep` - Search file contents with regex
+  - `web_search` - Search the web for information
+  - `web_fetch` - Fetch and parse web pages
+  - `todo_manager` - Task planning and tracking
+  - `run_project` - Project dev server management
+- **Session Management**: Save, resume, and list conversation sessions
+- **Permission Modes**: 
+  - `auto_approve` - Automatically execute all tools
+  - `confirm_safes` - Auto-execute safe operations, confirm risky ones
+  - `confirm_edits` - Confirm file edits only
+  - `confirm_all` - Confirm every tool execution
+  - `plan_only` - Plan without executing
+- **Cost Control**: Track and limit API usage costs
+- **Message Compression**: Automatic conversation history compression
+- **Project Rules**: Support for `.clackyrules`, `.cursorrules`, and `CLAUDE.md`
+- **Interactive Confirmations**: Preview diffs and shell commands before execution
+- **Hook System**: Extensible event hooks for customization
+
+### Changed
+- Refactored architecture to support autonomous agent capabilities
+- Enhanced CLI with agent command and session management
+- Improved error handling and retry logic for network failures
+- Better progress indicators during API calls and compression
+
+### Fixed
+- API compatibility issues with different providers
+- Session restoration with error recovery
+- Tool execution feedback loop
+- Safe shell command validation
+- Edit tool string matching and preview
+
+## [0.1.0] - 2025-12-27
+
+### Added
+- Initial release of Clacky
+- Interactive chat mode for conversations with Claude
+- Single message mode for quick queries
+- Configuration management for API keys
+- Support for Claude 3.5 Sonnet model
+- Colorful terminal output with TTY components
+- Secure API key storage in `~/.clacky/config.yml`
+- Multi-turn conversation support with context preservation
+- Command-line interface powered by Thor
+- Comprehensive test suite with RSpec
+
+### Features
+- `clacky chat [MESSAGE]` - Start interactive chat or send single message
+- `clacky config set` - Configure API key
+- `clacky config show` - Display current configuration
+- `clacky version` - Show version information
+- Model selection via `--model` option
+
+[Unreleased]: https://github.com/yafeilee/clacky/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/yafeilee/clacky/compare/v0.1.0...v0.5.0
+[0.1.0]: https://github.com/yafeilee/clacky/releases/tag/v0.1.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 windy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,272 @@
+# Clacky
+
+A command-line interface for interacting with AI models. Clacky supports OpenAI-compatible APIs, making it easy to chat with various AI models directly from your terminal.
+
+## Features
+
+- 💬 Interactive chat sessions with AI models
+- 🤖 Autonomous AI agent with tool use capabilities
+- 🚀 Single-message mode for quick queries
+- 🔐 Secure API key management
+- 📝 Multi-turn conversation support
+- 🎨 Colorful terminal output
+- 🌐 OpenAI-compatible API support (OpenAI, Gitee AI, DeepSeek, etc.)
+- 🛠️ Rich built-in tools: file operations, web search, code execution, and more
+
+## Installation
+
+Install the gem by executing:
+
+```bash
+gem install clacky
+```
+
+Or add it to your Gemfile:
+
+```bash
+bundle add clacky
+```
+
+For development from source:
+
+```bash
+git clone https://github.com/yafeilee/clacky.git
+cd clacky
+bundle install
+bin/clacky
+```
+
+## Configuration
+
+Before using Clacky, you need to configure your settings:
+
+```bash
+clacky config set
+```
+
+You'll be prompted to enter:
+- **API Key**: Your API key from any OpenAI-compatible provider
+- **Model**: Model name (e.g., `gpt-4`, `deepseek-chat`)
+- **Base URL**: OpenAI-compatible API endpoint (e.g., `https://api.openai.com/v1`)
+
+To view your current configuration:
+
+```bash
+clacky config show
+```
+
+## Usage
+
+### Interactive Chat Mode
+
+Start an interactive chat session:
+
+```bash
+clacky chat
+```
+
+Type your messages and press Enter. Type `exit` or `quit` to end the session.
+
+### Single Message Mode
+
+Send a single message and get a response:
+
+```bash
+clacky chat "What is Ruby?"
+```
+
+### Specify Model
+
+You can specify which model to use (overrides config):
+
+```bash
+clacky chat --model=gpt-4 "Hello!"
+```
+
+### AI Agent Mode (Interactive)
+
+Run an autonomous AI agent in interactive mode. The agent can use tools to complete tasks and runs in a continuous loop, allowing you to have multi-turn conversations with tool use capabilities.
+
+```bash
+# Start interactive agent (will prompt for tasks)
+clacky agent
+
+# Start with an initial task, then continue interactively
+clacky agent "Create a README.md file for my project"
+
+# Auto-approve all tool executions
+clacky agent --mode=auto_approve
+
+# Work in a specific project directory
+clacky agent --path /path/to/project
+
+# Limit tools available to the agent
+clacky agent --tools file_reader glob grep
+```
+
+The agent will:
+1. Complete each task using its React (Reason-Act-Observe) cycle
+2. Show you the results
+3. Wait for your next instruction
+4. Maintain conversation context across tasks
+5. Type 'exit' or 'quit' to end the session
+
+#### Permission Modes
+
+- `confirm_all` (default) - Confirm every tool use
+- `confirm_edits` - Auto-approve read-only tools, confirm edits
+- `auto_approve` - Automatically execute all tools (use with caution)
+- `plan_only` - Generate plan without executing
+
+#### Agent Options
+
+```bash
+--path PATH                    # Project directory (defaults to current directory)
+--mode MODE                    # Permission mode
+--tools TOOL1 TOOL2            # Allowed tools (or "all")
+--max-iterations N             # Maximum iterations (default: 50)
+--max-cost N                   # Maximum cost in USD (default: 5.0)
+--verbose                      # Show detailed output
+```
+
+#### Cost Control & Memory Management
+
+The agent includes intelligent cost control features:
+
+- **Automatic Message Compression**: When conversation history grows beyond 30 messages, the agent automatically compresses older messages into a summary, keeping only the system prompt and the most recent 10 messages. This dramatically reduces token costs for long-running tasks (achieves ~60% compression ratio).
+
+- **Configurable Limits**:
+  - `max_iterations`: Maximum number of agent loops (default: 50)
+  - `max_cost_usd`: Maximum total cost in USD (default: $5.00)
+  - `timeout_seconds`: Maximum execution time (default: 600s)
+
+- **Compression Settings**:
+  - `enable_compression`: Enable/disable automatic compression (default: true)
+  - `keep_recent_messages`: Number of recent messages to preserve (default: 10)
+  - Compression triggers at: `keep_recent_messages + 20` messages
+
+Example with custom limits:
+```bash
+clacky agent --max-iterations=100 --max-cost=10.0 --verbose
+```
+
+### List Available Tools
+
+View all built-in tools:
+
+```bash
+clacky tools
+
+# Filter by category
+clacky tools --category file_system
+```
+
+#### Built-in Tools
+
+- **todo_manager** - Manage TODO items for task planning and tracking
+- **file_reader** - Read file contents
+- **write** - Create or overwrite files
+- **edit** - Make precise edits to existing files
+- **glob** - Find files by pattern matching
+- **grep** - Search file contents with regex
+- **shell** - Execute shell commands
+- **calculator** - Perform mathematical calculations
+- **web_search** - Search the web for information
+- **web_fetch** - Fetch and parse web page content
+
+### Available Commands
+
+```bash
+clacky chat [MESSAGE]     # Start a chat or send a single message
+clacky agent [MESSAGE]    # Run autonomous agent with tool use
+clacky tools              # List available tools
+clacky config set         # Set your API key
+clacky config show        # Show current configuration
+clacky version            # Show clacky version
+clacky help               # Show help information
+```
+
+## Examples
+
+### Chat Examples
+
+```bash
+# Quick question
+clacky chat "Explain closures in Ruby"
+
+# Start interactive session
+clacky chat
+
+# Check version
+clacky version
+```
+
+### Agent Examples
+
+```bash
+# Start interactive agent session
+clacky agent
+# Then type tasks interactively:
+# > Create a TODO.md file with 3 example tasks
+# > Now add more items to the TODO list
+# > exit
+
+# Start with initial task, then continue
+clacky agent "Add a .gitignore file for Ruby projects"
+# After completing, agent waits for next task
+# > List all Ruby files
+# > Count lines in each file
+# > exit
+
+# Auto-approve mode for trusted operations
+clacky agent --mode=auto_approve --path ~/my-project
+# > Count all lines of code
+# > Create a summary report
+# > exit
+
+# Use specific tools only in interactive mode
+clacky agent --tools file_reader glob grep
+# > Find all TODO comments
+# > Search for FIXME comments
+# > exit
+
+# Using TODO manager for complex tasks
+clacky agent "Implement a new feature with user authentication"
+# Agent will:
+# 1. Use todo_manager to create a task plan
+# 2. Add todos: "Research current auth patterns", "Design auth flow", etc.
+# 3. Complete each todo step by step
+# 4. Mark todos as completed as work progresses
+# > exit
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+### Testing Agent Features
+
+After making changes to agent-related functionality (tools, system prompts, agent logic, etc.), test with this command:
+
+```bash
+# Test agent with a complex multi-step task using auto-approve mode
+echo "Create a simple calculator project with index.html, style.css, and script.js files" | \
+  bin/clacky agent --mode=auto_approve --path=tmp --max-iterations=20
+
+# Expected: Agent should plan tasks (add TODOs), execute them (create files),
+# and track progress (mark TODOs as completed)
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/clacky. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/clacky/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Clacky project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/clacky/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]