🚀 Hypz CLI - Autonomous Developer Agent

An autonomous developer agent that takes project requests and completes them fully with minimal interruptions. Hypz runs directly in your terminal on any OS (Linux, macOS, Windows) and can create entire projects, fix errors, and execute tasks independently.

📦 Installation

Quick Install (Recommended)

Using curl:

curl -fsSL https://raw.githubusercontent.com/ysr-hameed/hypz-cli/main/install.sh | bash

Using wget:

wget -qO- https://raw.githubusercontent.com/ysr-hameed/hypz-cli/main/install.sh | bash

NPM Install

npm install -g hypz-cli

Manual Install

git clone https://github.com/ysr-hameed/hypz-cli.git
cd hypz-cli
npm install
npm run build
npm link

Requirements

• Node.js v16 or higher
• npm or yarn

✨ Features

• 🤖 Fully Autonomous Agent: NEW v2.0 - Complete autonomous mode that plans, builds, installs, runs, and auto-fixes projects
• 💬 Direct Chat Mode: Just run hypz run to start chatting - no prompts, instant conversation
• 📊 Real-time Streaming: See code generate live with streaming support for all major LLM providers
• 🌐 Multi-LLM Support: OpenRouter, ChatGPT, Claude, Gemini, Grok, DeepSeek, Mistral, and custom providers
• 📁 Complete Project Management: Creates, edits, renames, and deletes files and folders
• 🔧 Terminal Integration: Runs real commands and shows actual output
• 💾 Persistent Context: Maintains memory of project state throughout task execution
• 🎨 Beautiful CLI UI: Clean, modern interface with detailed progress tracking
• 🔒 Secure Configuration: API keys stored securely in local config with file permissions
• ⚡ Enhanced Logging: Line-by-line diffs, exact timing (to millisecond), real-time progress
• 🛡️ Permission System: Asks before running sensitive commands (rm -rf, sudo, etc.)

🚀 Quick Start

1. Initialize Configuration

Run the setup command to configure your LLM provider:

hypz start

This will guide you through:

• Selecting an LLM provider (ChatGPT, Claude, Gemini, Grok, OpenRouter, or Custom)
• Choosing a model
• Entering your API key
• Validating the connection

2. Full Autonomous Mode (NEW in v2.0!)

The most powerful way to use Hypz - full autonomous agent that handles everything:

hypz auto "create a todo app with React and Node.js"
# or use the alias
hypz agent "build a weather dashboard"

What the autonomous agent does:

1. 📋 Phase 1: Planning - Creates a detailed architectural plan
2. 📝 Phase 2: Code Generation - Generates all files with complete, production-ready code
3. 🔧 Phase 3: Setup - Installs all dependencies automatically
4. 🚀 Phase 4: Execution - Runs your project
5. 🔧 Phase 5: Auto-Fix - If errors occur, analyzes and fixes them (up to 5 attempts)

The agent will:

• Create a plan.md file with the full project architecture
• Generate ALL code files with NO placeholders
• Run npm install, pip install, or other setup commands
• Execute the project (start servers, run tests, etc.)
• Automatically detect and fix errors
• Show real-time streaming output

Interactive autonomous mode:

hypz auto
# Enter tasks one by one, agent executes each fully

3. Chat Mode

Just run hypz run without any arguments to start an interactive chat:

hypz run

This opens a conversational interface where you can:

• Ask questions
• Request code generation
• Make file changes
• Run commands
• Get help with errors

Type exit or quit to end the session.

4. Or Run a Specific Task (Classic Mode)

Describe what you want to build:

hypz run "Create a REST API for managing student results"

4. View Configuration

Check your current configuration:

hypz config

🎯 Usage Examples

🤖 Autonomous Mode (NEW in v2.0!)

The ultimate hands-off experience:

$ hypz auto "create a REST API for blog posts with Express and MongoDB"

🤖 AUTONOMOUS AGENT MODE ACTIVATED

I will now autonomously:
  1️⃣  Create a detailed plan
  2️⃣  Generate all code files
  3️⃣  Install dependencies
  4️⃣  Run your project
  5️⃣  Auto-fix any errors

📋 PHASE 1: Creating Detailed Plan
✓ Plan created!

📊 Project Plan:
Name: Blog API
Language: JavaScript
Framework: Express.js

📝 PHASE 2: Generating All Code Files
  ✓ package.json (25 lines)
  ✓ server.js (150 lines)
  ✓ models/Post.js (45 lines)

🔧 PHASE 3: Running Setup Commands
$ npm install
✓ Done

🚀 PHASE 4: Running Project
$ npm start
✓ Project started successfully

✨ SUCCESS! Your project is ready!

Interactive Chat Mode

Start chatting directly:

$ hypz run

💬 Conversational Mode
ℹ Chat with Hypz AI Agent. Type your requests or questions.
ℹ Type 'exit' or 'quit' to end the conversation.

You: create a simple express server
Agent: I'll create an Express server for you...
[Creates files with real-time streaming]

You: add error handling
Agent: Adding comprehensive error handling...
[Updates files]

You: exit

Create a Backend API

hypz run "Make a CRUD API for managing student results in a backend folder with Express and TypeScript"

Build a Frontend App

hypz run "Create a React Todo app with TypeScript, Tailwind CSS, and local storage"

Set Up a Full Stack Project

hypz run "Initialize a Next.js project with TypeScript, Prisma, and PostgreSQL integration"

Fix and Improve

hypz run "Add error handling and input validation to the existing API"

🔧 Supported LLM Providers

Latest AI Models

• ChatGPT (OpenAI): gpt-4-turbo, gpt-4o, gpt-4o-mini
• Claude (Anthropic): claude-3-5-sonnet-20241022, claude-3-opus, claude-3-sonnet
• Gemini (Google): gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash
• DeepSeek: deepseek-chat, deepseek-coder (optimized for coding)
• Grok (xAI): grok-beta, grok-2
• Mistral AI: mistral-large-latest, mistral-medium-latest
• OpenRouter: Access to multiple models through one API
• Custom Model: Use any OpenAI-compatible API

Getting API Keys

• OpenAI: https://platform.openai.com/api-keys
• Anthropic: https://console.anthropic.com/
• Google: https://makersuite.google.com/app/apikey
• DeepSeek: https://platform.deepseek.com/
• xAI: https://x.ai/
• Mistral: https://console.mistral.ai/
• OpenRouter: https://openrouter.ai/keys

💡 Advanced Features

Intelligent Error Recovery

Hypz automatically:

• Detects compilation and runtime errors
• Analyzes error messages and stack traces
• Fixes root causes, not just symptoms
• Verifies fixes work before continuing

Interactive Problem Solving

When you report an issue:

hypz run "I'm getting an error when running npm start"

Hypz will:

1. Ask for the exact error message
2. Analyze your codebase
3. Identify the root cause
4. Implement a fix
5. Verify it works

Detailed Terminal Output

Every action is logged in detail:

• API Call Tracking: See response times and which model is being called
• File Diffs: Line-by-line changes with ++ (added) and -- (removed) indicators
• Command Execution: Full output from every terminal command
• AI Reasoning: Understand why the AI makes specific decisions
• Real-time Progress: Live updates for each step

See ENHANCED_LOGGING.md for more details.

Smart Code Generation

• Generates complete, production-ready code
• No placeholders or "TODO" comments
• Includes error handling and edge cases
• Follows best practices and conventions
• Adds documentation and comments

🏗️ How It Works

1. Understanding: Hypz analyzes your request and breaks it into actionable steps
2. Planning: Generates a complete execution plan
3. Execution: Creates files, installs dependencies, runs commands
4. Error Detection: Automatically detects and fixes errors
5. Iteration: Continues working until the task is fully complete
6. Summary: Provides a comprehensive report of all changes

🎨 Project Structure

hypz-cli/
├── src/
│   ├── commands/           # CLI commands
│   │   ├── start.ts       # Setup flow
│   │   ├── run.ts         # Task execution
│   │   └── config.ts      # Configuration management
│   ├── llm/
│   │   └── client.ts      # LLM provider clients
│   ├── utils/
│   │   ├── config.ts      # Config storage
│   │   ├── filesystem.ts  # File operations
│   │   ├── terminal.ts    # Command execution
│   │   └── ui.ts          # UI components
│   ├── types/
│   │   └── index.ts       # TypeScript types
│   ├── cli.ts             # CLI entry point
│   └── index.ts           # Module exports
├── package.json
├── tsconfig.json
└── README.md

🔒 Security

• API keys are stored locally in ~/.hypz/config.json
• Keys are never logged or displayed in full
• Destructive operations require confirmation
• All data stays on your machine

🛠️ Development

Build from Source

# Clone the repository
git clone https://github.com/yourusername/hypz-cli.git
cd hypz-cli

# Install dependencies
npm install

# Build
npm run build

# Link for local development
npm link

# Run
hypz start

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Watch mode for development
• npm run lint - Run ESLint
• npm test - Run tests

📝 Configuration File

Configuration is stored at: ~/.hypz/config.json

Example structure:

{
    "llm": {
        "provider": "chatgpt",
        "model": "gpt-4-turbo-preview",
        "apiKey": "sk-..."
    },
    "lastUpdated": "2025-12-05T00:00:00.000Z"
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details

🐛 Troubleshooting

"No configuration found"

Run hypz start to set up your LLM provider.

API Connection Failed

• Verify your API key is correct
• Check your internet connection
• Ensure you have credits/quota remaining with your provider

Command Execution Errors

• Hypz will automatically attempt to fix most errors
• Check that required tools (npm, node, etc.) are installed
• Review the error output for specific issues

🌟 Features Coming Soon

• Project templates
• Git integration
• Multi-language support
• Team collaboration features
• Custom agent personalities
• Plugin system

💬 Support

For issues, questions, or suggestions, please open an issue on GitHub.

Made with ❤️ by the Hypz team