Flutty CLI Agent

A Claude Code CLI clone built using the DeepSeek API. This tool provides an interactive coding assistant that can help with software engineering tasks, code analysis, file operations, and more.

Features

• Interactive Chat Mode: Real-time conversation with the AI assistant
• One-shot Queries: Execute single commands and get results
• Comprehensive Tool Set: File operations, code search, bash commands, and more
• Todo List Management: Automatically tracks complex multi-step tasks
• Safety Features: Command validation, sandboxed execution, and security checks

Available Tools

• Read: Read files with syntax highlighting and line numbers
• Write: Create new files or overwrite existing ones
• Edit: Perform targeted edits with diff display
• Grep: Powerful regex search across your codebase (uses ripgrep when available)
• Glob: Fast file pattern matching
• Bash: Execute shell commands with safety checks and timeouts
• TodoWrite: Track and manage complex tasks

Installation

1. Clone or copy the project
2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Run initial setup:

   npm run dev setup

Configuration

The setup command will create a .env file with your DeepSeek API key. You can also manually configure:

# Required
DEEPSEEK_API_KEY=your_api_key_here

# Optional
CLI_LOG_LEVEL=info
CLI_MAX_TOKENS=8000
CLI_TEMPERATURE=0.7
CLI_MAX_TURNS=50
ENABLE_BASH_TOOL=true
BASH_TIMEOUT_MS=30000

Usage

Interactive Chat

Start an interactive session:

flutty chat
# or
flutty c

Options:

• -d, --directory <path>: Set working directory
• -m, --model <model>: Choose DeepSeek model (deepseek-chat, deepseek-coder)
• -v, --verbose: Enable debug logging

One-shot Query

Execute a single query:

flutty query "Help me fix the bug in src/app.js"
# or
flutty q "Create a new React component for user authentication"

Configuration

View current settings:

flutty config

Examples

# Start interactive chat in specific directory
flutty chat -d ./my-project -v

# Quick file analysis
flutty query "What does the main function in app.py do?"

# Code generation
flutty query "Create a TypeScript interface for a user profile"

# Debugging help
flutty query "There's an error in my React component, can you help fix it?"

Development

# Development mode (with TypeScript compilation)
npm run dev

# Build for production
npm run build

# Run built version
npm start

# Run tests
npm test

# Lint code
npm run lint

Architecture

Based on the Claude Code architecture with:

• Master Loop: Single-threaded execution loop for predictable behavior
• Tool System: Modular tools that can be easily extended
• DeepSeek Integration: Uses OpenAI-compatible API for seamless integration
• Safety Features: Command validation, timeouts, and sandboxing
• Context Management: Tracks conversation state and active files

Safety and Security

• Commands are validated for dangerous patterns
• File access is logged and monitored
• Bash commands have configurable timeouts
• All tool executions are logged for auditing

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Troubleshooting

Common Issues

API Key not found

• Run flutty setup to configure your environment
• Ensure .env file is in your working directory

Tool not found errors

• Make sure all dependencies are installed with npm install
• Check that ripgrep is installed for enhanced search functionality

Permission errors

• Verify the CLI has read/write access to your working directory
• Check that the ENABLE_BASH_TOOL setting matches your security requirements