cyne-cli 1.0.3

A powerful ReAct Python Assistant with AI capabilities

cyne CLI - Your AI Developer Assistant in the Terminal 🚀

cyne-CLI is a powerful ReAct (Reasoning and Acting) Python assistant with AI capabilities, featuring Claude CLI-style tool displays, persistent task management, and professional terminal UI.

Made by Cynerza

✨ Features

• 🤖 AI-Powered Assistant - Advanced reasoning with LangGraph and OpenAI
• 📋 Plan Management - Create, track, and complete tasks with strikethrough formatting
• 🔧 Multiple Tools - Web search, file operations, bash commands, and more
• 💭 Think Mode - Enhanced reasoning for complex problems
• 🎨 Rich Terminal UI - Beautiful formatting with colors and progress tracking
• 💾 Persistent Storage - Plans and session history automatically saved
• 🚀 Multiple Run Methods - CLI command or Python module execution

📦 Installation

From PyPI (Recommended)

pip install cyne-cli

From Source (Development)

git clone https://github.com/Cynerza/cyne-cli.git
cd cyne-cli
pip install -e .

🚀 Quick Start

Basic Usage

# Interactive mode
cyne

# Single prompt
cyne "Hello, how can you help me?"

# Think mode for complex reasoning
cyne --think "Analyze this complex problem"

# Show help
cyne --help

# Check version
cyne --version

Python Module Execution

# All commands work with module execution too
python3 -m cyne
python3 -m cyne "Hello world"
python3 -m cyne --think "Complex reasoning task"

📋 Plan Management

cyne-CLI includes a powerful plan tool for organizing and tracking tasks with visual progress indicators.

Creating Plans

# Create a plan with multiple tasks
cyne "Create a plan for building a website with tasks: Setup HTML, Add CSS, JavaScript functionality, Testing, Deployment"

Output:

• Website Project
Build a responsive website

  ☐ Setup HTML structure
  ☐ Add CSS styling  
  ☐ JavaScript functionality
  ☐ Testing across browsers
  ☐ Deployment

Progress: 0/5 items completed (0.0%)

Managing Tasks

# Complete a task (adds strikethrough)
cyne "Complete the HTML setup task"

# Add new tasks
cyne "Add a new task: Add responsive design"

# View all plans
cyne "List all my plans"

# Show specific plan
cyne "Show me the website project plan"

Completed tasks show with strikethrough:

• Website Project
Build a responsive website

  ☑ Setup HTML structure        # ✅ Completed with strikethrough
  ☐ Add CSS styling
  ☐ JavaScript functionality
  ☐ Testing across browsers
  ☐ Deployment

Progress: 1/5 items completed (20.0%)

Plan Tool Commands

# Direct plan tool usage
cyne "Use plan tool to: create plan \"Project Name\" \"Description\" [\"Task 1\", \"Task 2\"]"
cyne "Use plan tool to: complete item plan_id item_id"
cyne "Use plan tool to: add item plan_id \"New task\""
cyne "Use plan tool to: list plans"

🛠️ Available Tools

Core Tools

• 🧠 Think Tool - Advanced reasoning and problem analysis
• 📋 Plan Tool - Task management with progress tracking
• 🔍 Web Search - Real-time information retrieval with Brave Search
• 📁 File Operations - Read, write, and edit files with permission system
• 💻 Bash Commands - Execute system commands safely
• ✏️ File Editing - Smart file editing with diff previews

Tool Examples

# Web search
cyne "Search for latest Python best practices"

# File operations
cyne "Read the config.json file and explain its structure"
cyne "Create a new Python script for data processing"

# System commands
cyne "Check disk usage and system status"

# Complex reasoning
cyne --think "Analyze the pros and cons of different deployment strategies"

📊 Session Management

History & Statistics

# View session history
cyne --history

# Show usage statistics
cyne --stats

# Resume previous conversation
cyne "Resume our last conversation about the website project"

Data Storage

• Plans: .cyne_data/plans.json - All task plans and progress
• Sessions: Stored in memory during runtime
• Configuration: Automatic environment detection

🎯 Usage Examples

Development Workflow

# 1. Create project plan
cyne "Create a plan for building a Python web scraper with tasks: Setup environment, Design data model, Implement scraper, Add error handling, Write tests, Documentation"

# 2. Work through tasks
cyne "Complete the environment setup task"
cyne "Help me implement the data model for the scraper"

# 3. Track progress
cyne "Show my scraper project progress"

Learning & Research

# Complex analysis with think mode
cyne --think "Explain the differences between async/await and threading in Python, with practical examples"

# Research with web search
cyne "Find the latest best practices for FastAPI development"

# Create learning plan
cyne "Create a learning plan for mastering React with tasks: JSX basics, Components, State management, Hooks, Routing, Testing"

System Administration

# System monitoring
cyne "Check system resources and suggest optimizations"

# File management
cyne "Organize the Downloads folder by file type"

# Documentation
cyne "Create documentation for this Python project based on the code structure"

⚙️ Configuration

Environment Setup

Create a .env file in your project directory with your API keys:

# OpenAI (Primary)
OPENAI_API_KEY=sk-...

# Optional: Other providers
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...

# Web Search (Recommended)
BRAVE_SEARCH_API_KEY=...

Using Custom Environment Files

# Run with specific environment file
cyne -e .env.dev "Your query here"
cyne -e .env.production "Deploy the application"

Command Line Options

cyne --help                    # Show all options
cyne --think                   # Enable think mode
cyne --test                    # Run test queries
cyne --history                 # Manage session history
cyne --stats                   # Show usage statistics
cyne --version                 # Show version info

🎨 Rich Terminal UI

cyne-CLI provides a beautiful terminal experience with:

• 🎨 Syntax highlighting for code and diffs
• 📊 Progress bars for task completion
• ✅ Strikethrough formatting for completed tasks
• 🔧 Claude CLI-style tool call displays
• 📱 Responsive layout that adapts to terminal size

🏗️ Architecture

Package Structure

cyne/
├── __init__.py              # Package initialization
├── __main__.py              # Module execution entry point
├── cli.py                   # Command-line interface
├── core/                    # Core functionality
│   ├── __init__.py
│   ├── agent_manager.py     # Agent creation and management
│   ├── session_history.py  # Session persistence
│   └── prompt_system.py    # System prompts and plan integration
└── tools/                   # Available tools
    ├── __init__.py
    ├── plan_tool.py         # Task management with Rich UI
    ├── brave_search_tool.py # Web search functionality
    ├── file_read_tool.py    # File reading operations
    ├── file_write_tool.py   # File writing with previews
    ├── file_edit_tool.py    # File editing with diffs
    ├── bash_run_tool.py     # System command execution
    └── think_tool.py        # Advanced reasoning

Data Storage

.cyne_data/
└── plans.json               # Persistent plan storage

Technology Stack

• LangGraph 0.6.2 - Agent orchestration and state management
• LangChain - LLM integration and tool management
• Rich 14.1.0 - Beautiful terminal UI with formatting
• Pydantic - Data validation and settings
• OpenAI/Compatible APIs - Language model inference

🧪 Development

Setting Up Development Environment

# Clone repository
git clone https://github.com/Cynerza/cyne-cli.git
cd cyne-cli

# Install in development mode
pip install -e .

# Run tests
python -m pytest

# Run with development logging
cyne --debug "Test message"

Adding New Tools

1. Create tool class in cyne/tools/ following the pattern:

from langchain.tools import BaseTool
from pydantic import Field

class MyCustomTool(BaseTool):
    name: str = "my_custom_tool"
    description: str = "Description of what the tool does"
    
    def _run(self, query: str) -> str:
        # Tool implementation
        return result

2. Add to cyne/tools/__init__.py:

from .my_custom_tool import MyCustomTool
__all__ = [..., "MyCustomTool"]

3. Import in cyne/core/agent_manager.py and add to tools list

Extending Plan Tool

The plan tool supports rich formatting and persistence:

# Custom plan actions
plan_manager = PlanManager()
plan_id = plan_manager.create_plan("My Plan", "Description", ["Task 1", "Task 2"])
plan_manager.complete_item(plan_id, "item_1")

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guidelines
• Add type hints to all functions
• Write docstrings for public methods
• Add tests for new functionality
• Update documentation for new features

🐛 Troubleshooting

Common Issues

Installation Problems

# If pip install fails, try upgrading pip
pip install --upgrade pip
pip install -e .

Missing API Keys

# Set OpenAI API key
export OPENAI_API_KEY="your-key-here"

# Verify configuration
cyne "Test API connection"

Permission Errors

# Check file permissions
ls -la ~/.cyne_data/

# Reset permissions if needed
chmod 755 ~/.cyne_data/
chmod 644 ~/.cyne_data/plans.json

Debug Mode

# Enable debug logging
cyne --debug "Your query here"

# View detailed error information
cyne --verbose "Your query here"

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with LangChain and LangGraph
• UI powered by Rich
• Inspired by Claude CLI
• Task management inspired by modern todo applications

📞 Support

• 🌐 Visit: cynerza.com | cyne.com
• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: Wiki

🚀 Roadmap

Upcoming Features

• 📱 Mobile companion app - Control cyne from your phone
• 🔌 Plugin system - Community-driven tool ecosystem
• 🌐 Web interface - Browser-based interaction
• 📊 Analytics dashboard - Usage insights and productivity metrics
• 🤝 Team collaboration - Shared plans and project management
• 🔄 CI/CD integration - Automated workflows and deployments

Version History

• v1.0.0 - Initial release with plan tool and Rich UI
• v0.9.0 - Claude CLI-style tool displays
• v0.8.0 - Package structure and pip distribution
• v0.7.0 - Think mode and advanced reasoning

---

Made with ❤️ by Cynerza | Explore cynerza.com | Visit cyne.com

Empowering developers with AI-assisted productivity