hypz-cli

v3.0.8

Published

2 months ago

An advanced autonomous developer agent powered by state-of-the-art LLMs with intelligent error recovery and adaptive problem-solving

🚀 Hypz - Autonomous AI Development Agent# 🚀 Hypz CLI - Autonomous Developer Agent

Your AI pair programmer that works autonomously. Hypz is an intelligent development agent that understands your requirements, plans the architecture, writes production-ready code, and handles deployment - all from a single command.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.

🎉 What's New in v3.0.3

Critical UX & Safety Improvements:

✅ Command Naming: Use hypz run as the main command (aligns with run.ts file) - both hypz run and hypz [prompt] work
✅ Ctrl+C Support: Press Ctrl+C during execution to stop gracefully and return to prompt (doesn't exit the whole program!)
✅ Consistent Terminology: Changed "task" → "prompt" throughout the UI for clarity
- "Enter your prompt:" instead of "What should I build?"
- "📋 Prompt:" instead of "📋 Task:"
✅ Better Iteration Control: AI properly exits when done (respects nextStep='done')
✅ Interruption Checking: Built-in support to detect and handle user interruptions mid-execution

Previous Updates (v3.0.0-3.0.2):

Smart task validation (detects vague prompts like "agent", "test")
Enhanced permission system (30+ sensitive command patterns)
User confirmation before execution
Better context awareness (shows existing files)
Clean, minimal output (80% less verbose)
Server auto-timeout (10 seconds for testing)
Streaming fixes (no more instant dumps)
No duplicate file displays

💡 Why Hypz?## 📦 Installation

Most AI coding tools require constant hand-holding. Hypz works differently:### Quick Install (Recommended)

🎯 Truly Autonomous: Describe what you want, Hypz handles everythingUsing curl:
🔄 Self-Correcting: Automatically detects and fixes errors
📊 Context-Aware: Analyzes your existing project before making changes```bash
⚡ Real-Time Visibility: See every decision and action as it happenscurl -fsSL https://raw.githubusercontent.com/ysr-hameed/hypz-cli/main/install.sh | bash
🛡️ Production-Ready: Follows best practices, adds proper error handling```

📦 Quick StartUsing wget:

Install```bash

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

bash

npm install -g hypz-cli




### Setup (One-Time)```bash

npm install -g hypz-cli

```bash```

hypz start

```### Manual Install



Choose your AI provider (OpenAI, Claude, Gemini, etc.) and enter your API key.```bash

git clone https://github.com/ysr-hameed/hypz-cli.git

### Usecd hypz-cli

npm install

```bashnpm run build

# Interactive mode - have a conversationnpm link

hypz```



# Direct task execution### Requirements

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

hypz "add authentication to my app"-   Node.js v16 or higher

hypz "fix the TypeScript errors"-   npm or yarn

✨ Features

That's it. Hypz does the rest.

🤖 Fully Autonomous Agent: NEW v2.0 - Complete autonomous mode that plans, builds, installs, runs, and auto-fixes projects

🎯 What Can Hypz Do?- 💬 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

🏗️ Build Complete Projects- 🌐 Multi-LLM Support: OpenRouter, ChatGPT, Claude, Gemini, Grok, DeepSeek, Mistral, and custom providers

📁 Complete Project Management: Creates, edits, renames, and deletes files and folders


$ hypz "build a todo app with React, TypeScript, and Tailwind"-   💾 **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

   🎯 STARTING AUTONOMOUS EXECUTION-   ⚡ **Enhanced Logging**: Line-by-line diffs, exact timing (to millisecond), real-time progress

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━-   🛡️ **Permission System**: Asks before running sensitive commands (rm -rf, sudo, etc.)



📋 Task: build a todo app with React, TypeScript, and Tailwind## 🚀 Quick Start



🔗 Testing connection to claude...### 1. Initialize Configuration

✓ Connected to claude (claude-3-5-sonnet-20241022)

Run the setup command to configure your LLM provider:

━━━ PROJECT ANALYSIS ━━━

📁 Empty directory (new project)```bash

━━━━━━━━━━━━━━━━━━━━━━hypz start

🧠 AI Agent analyzing your request...

This will guide you through:

💭 I will create a modern todo app using React 18, TypeScript, Vite for fast builds,

and Tailwind CSS for styling. The app will have CRUD operations, local storage- Selecting an LLM provider (ChatGPT, Claude, Gemini, Grok, OpenRouter, or Custom)

persistence, and a clean UI with dark mode support.- Choosing a model

Entering your API key

✓ Ready to execute- Validating the connection

📝 File Operations:### 2. Full Autonomous Mode (NEW in v2.0!)

→ create package.jsonThe most powerful way to use Hypz - full autonomous agent that handles everything:

✓ create package.json (28 lines)


→ create vite.config.ts  hypz auto "create a todo app with React and Node.js"

✓ create vite.config.ts (12 lines)# or use the alias

hypz agent "build a weather dashboard"

→ create src/App.tsx```

✓ create src/App.tsx (156 lines)

**What the autonomous agent does:**

⚡ Commands:

1. 📋 **Phase 1: Planning** - Creates a detailed architectural plan

→ npm install2. 📝 **Phase 2: Code Generation** - Generates all files with complete, production-ready code

✓ Done (3.4s)3. 🔧 **Phase 3: Setup** - Installs all dependencies automatically

4. 🚀 **Phase 4: Execution** - Runs your project

→ npm run dev5. 🔧 **Phase 5: Auto-Fix** - If errors occur, analyzes and fixes them (up to 5 attempts)

Server running at http://localhost:5173

**The agent will:**

✨ Task completed successfully!

```-   Create a `plan.md` file with the full project architecture

-   Generate ALL code files with NO placeholders

### 🔧 Modify Existing Projects-   Run `npm install`, `pip install`, or other setup commands

-   Execute the project (start servers, run tests, etc.)

```bash-   Automatically detect and fix errors

$ cd my-existing-app-   Show real-time streaming output

$ hypz "add dark mode toggle to the app"

**Interactive autonomous mode:**

━━━ PROJECT ANALYSIS ━━━

```bash

📦 Node.js Projecthypz auto

   Name: my-app# Enter tasks one by one, agent executes each fully

   Framework: React```

   Language: TypeScript

   Dependencies: react, tailwindcss, vite### 3. Chat Mode

   Scripts: dev, build, preview

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

📂 Structure:

   ✓ src/ directory```bash

   ✓ public/hypz run

━━━━━━━━━━━━━━━━━━━━━━

This opens a conversational interface where you can:

💭 I found a React + Tailwind app. I'll add a dark mode toggle using

React Context and localStorage for persistence...- Ask questions

Request code generation

📝 File Operations:- Make file changes

Run commands

→ create src/contexts/ThemeContext.tsx- Get help with errors

✓ create src/contexts/ThemeContext.tsx (45 lines)

Type exit or quit to end the session.

→ edit src/App.tsx

✓ edit src/App.tsx (23 lines changed)### 4. Or Run a Specific Task (Classic Mode)

✨ Complete! Dark mode toggle added.Describe what you want to build:


```bash

### 🐛 Debug & Fix Issueshypz run "Create a REST API for managing student results"


$ hypz "fix the TypeScript errors in the project"### 4. View Configuration



🧠 Analyzing errors...Check your current configuration:



💭 I found 3 TypeScript errors:```bash

   - src/utils/api.ts: Missing return typehypz config

   - src/components/User.tsx: Props interface not defined  ```

   - src/hooks/useData.ts: Incorrect generic type

## 🎯 Usage Examples

📝 Applying fixes...

### 🤖 Autonomous Mode (NEW in v2.0!)

✓ Fixed all TypeScript errors

✓ All tests passingThe ultimate hands-off experience:


## ⚙️ Configuration$ hypz auto "create a REST API for blog posts with Express and MongoDB"



### View Current Config🤖 AUTONOMOUS AGENT MODE ACTIVATED



```bashI will now autonomously:

hypz config  1️⃣  Create a detailed plan

```  2️⃣  Generate all code files

  3️⃣  Install dependencies

### Change Provider  4️⃣  Run your project

  5️⃣  Auto-fix any errors

```bash

hypz start📋 PHASE 1: Creating Detailed Plan

```✓ Plan created!



### Supported AI Providers📊 Project Plan:

Name: Blog API

- **OpenAI**: GPT-4, GPT-4 Turbo, GPT-4oLanguage: JavaScript

- **Anthropic**: Claude 3.5 Sonnet, Claude 3 OpusFramework: Express.js

- **Google**: Gemini Pro, Gemini Flash

- **DeepSeek**: DeepSeek Chat, DeepSeek Coder📝 PHASE 2: Generating All Code Files

- **xAI**: Grok  ✓ package.json (25 lines)

- **Mistral AI**: Mistral Large  ✓ server.js (150 lines)

- **OpenRouter**: Access to multiple models  ✓ models/Post.js (45 lines)

- **Custom**: Bring your own LLM endpoint

🔧 PHASE 3: Running Setup Commands

## 🎓 How It Works$ npm install

✓ Done

### 1. **Deep Project Analysis**

Hypz first understands your project:🚀 PHASE 4: Running Project

- Detects frameworks and languages$ npm start

- Reads package.json and config files✓ Project started successfully

- Analyzes existing code structure

- Identifies installed dependencies✨ SUCCESS! Your project is ready!

2. Intelligent Planning

Creates an execution plan:### Interactive Chat Mode

Determines files to create/modify
Plans necessary commandsStart chatting directly:
Considers dependencies and order
Anticipates potential issues```bash

$ hypz run

3. Autonomous Execution

Executes the plan with real-time visibility:💬 Conversational Mode

Streams all output liveℹ Chat with Hypz AI Agent. Type your requests or questions.
Shows progress for each operationℹ Type 'exit' or 'quit' to end the conversation.
Runs commands with timeout protection
Handles errors automaticallyYou: create a simple express server

Agent: I'll create an Express server for you...

4. Self-Correction[Creates files with real-time streaming]

If something fails:

Analyzes the errorYou: add error handling
Determines root causeAgent: Adding comprehensive error handling...
Applies fix automatically[Updates files]
Retries operation
Repeats until successYou: exit


## 🛡️ Safety Features

### Create a Backend API

### Command Timeout Protection

- 30-second warning for long-running commands```bash

- 5-minute automatic timeouthypz run "Make a CRUD API for managing student results in a backend folder with Express and TypeScript"

- Prevents stuck processes```



### Smart Permissions### Build a Frontend App

Common operations (npm install, build, test) run automatically.

Dangerous operations (rm -rf, sudo, system changes) require confirmation.```bash

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

### Error Recovery```

- Detects compilation errors

- Catches runtime exceptions### Set Up a Full Stack Project

- Analyzes stack traces

- Auto-fixes when possible```bash

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

## 💻 Command Reference```



```bash### Fix and Improve

# Main command (interactive or direct)

hypz [task]```bash

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

# Setup/reconfigure```

hypz start

## 🔧 Supported LLM Providers

# View configuration

hypz config### Latest AI Models



# Get help-   **ChatGPT (OpenAI)**: `gpt-4-turbo`, `gpt-4o`, `gpt-4o-mini`

hypz --help-   **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`

# Check version-   **DeepSeek**: `deepseek-chat`, `deepseek-coder` (optimized for coding)

hypz --version-   **Grok (xAI)**: `grok-beta`, `grok-2`

```-   **Mistral AI**: `mistral-large-latest`, `mistral-medium-latest`

-   **OpenRouter**: Access to multiple models through one API

## 🎯 Best Practices-   **Custom Model**: Use any OpenAI-compatible API



### Be Specific### Getting API Keys

❌ "make an app"

✅ "create a blog API with Express, MongoDB, JWT auth"-   **OpenAI**: https://platform.openai.com/api-keys

-   **Anthropic**: https://console.anthropic.com/

### Provide Context-   **Google**: https://makersuite.google.com/app/apikey

❌ "add a feature"  -   **DeepSeek**: https://platform.deepseek.com/

✅ "add user registration to my Express API with email verification"-   **xAI**: https://x.ai/

-   **Mistral**: https://console.mistral.ai/

### Let It Work-   **OpenRouter**: https://openrouter.ai/keys

✅ Hypz shows real-time progress - watch but don't interrupt

✅ It will auto-fix most errors## 💡 Advanced Features

✅ Only intervene if it asks for clarification

### Intelligent Error Recovery

## 📊 Real-World Examples

Hypz automatically:

### E-Commerce Backend

```bash-   Detects compilation and runtime errors

hypz "create a REST API for an e-commerce store with products, -   Analyzes error messages and stack traces

     users, orders, and payments using Express, TypeScript, -   Fixes root causes, not just symptoms

     Prisma, and Stripe integration"-   Verifies fixes work before continuing

Interactive Problem Solving

Full-Stack Dashboard


hypz "build an analytics dashboard with Next.js 14, TypeScript,

     Chart.js, and a PostgreSQL backend with tRPC"```bash

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

Microservice


hypz "create a user authentication microservice with NestJS,

     JWT tokens, refresh tokens, email verification, and Redis"1. Ask for the exact error message

```2. Analyze your codebase

3. Identify the root cause

### Mobile Backend4. Implement a fix

```bash5. Verify it works

hypz "build a REST API for a mobile app with user profiles,

     posts, comments, likes, and real-time notifications using### Detailed Terminal Output

     Socket.io, Express, and PostgreSQL"

```Every action is logged in detail:



## 🔥 Advanced Features-   **API Call Tracking**: See response times and which model is being called

-   **File Diffs**: Line-by-line changes with `++` (added) and `--` (removed) indicators

### Multi-Step Projects-   **Command Execution**: Full output from every terminal command

Hypz can handle complex workflows:-   **AI Reasoning**: Understand why the AI makes specific decisions

1. Sets up project structure-   **Real-time Progress**: Live updates for each step

2. Installs all dependencies

3. Configures build toolsSee [ENHANCED_LOGGING.md](./ENHANCED_LOGGING.md) for more details.

4. Writes application code

5. Adds tests### Smart Code Generation

6. Runs and verifies

-   Generates complete, production-ready code

### Framework Detection-   No placeholders or "TODO" comments

Automatically recognizes:-   Includes error handling and edge cases

- React, Vue, Angular, Svelte-   Follows best practices and conventions

- Next.js, Nuxt, Remix, SvelteKit-   Adds documentation and comments

- Express, Fastify, NestJS, Koa

- And many more...## 🏗️ How It Works



### Existing Project Support1. **Understanding**: Hypz analyzes your request and breaks it into actionable steps

Works with any existing codebase:2. **Planning**: Generates a complete execution plan

- Analyzes current architecture3. **Execution**: Creates files, installs dependencies, runs commands

- Respects existing patterns4. **Error Detection**: Automatically detects and fixes errors

- Integrates seamlessly5. **Iteration**: Continues working until the task is fully complete

- Doesn't break working code6. **Summary**: Provides a comprehensive report of all changes



## 🐛 Troubleshooting## 🎨 Project Structure



### Connection Issues```

```bashhypz-cli/

# Verify your configuration├── src/

hypz config│   ├── commands/           # CLI commands

│   │   ├── start.ts       # Setup flow

# Reconfigure if needed│   │   ├── run.ts         # Task execution

hypz start│   │   └── config.ts      # Configuration management

```│   ├── llm/

│   │   └── client.ts      # LLM provider clients

### API Key Problems│   ├── utils/

Make sure your API key:│   │   ├── config.ts      # Config storage

- Is valid and active│   │   ├── filesystem.ts  # File operations

- Has sufficient credits/quota│   │   ├── terminal.ts    # Command execution

- Has access to the selected model│   │   └── ui.ts          # UI components

│   ├── types/

### Commands Stuck│   │   └── index.ts       # TypeScript types

Hypz automatically:│   ├── cli.ts             # CLI entry point

- Shows warning after 30 seconds│   └── index.ts           # Module exports

- Kills process after 5 minutes├── package.json

- Displays timeout message├── tsconfig.json

└── README.md

If needed, press `Ctrl+C` to cancel.```



## 📈 Performance## 🔒 Security



- **Context Analysis**: ~2 seconds-   API keys are stored locally in `~/.hypz/config.json`

- **File Operations**: Instant-   Keys are never logged or displayed in full

- **AI Response**: 3-10 seconds (streaming)-   Destructive operations require confirmation

- **Command Execution**: Depends on command-   All data stays on your machine

- **Error Detection**: Automatic and instant

## 🛠️ Development

## 🤝 Contributing

### Build from Source

We welcome contributions! Whether it's:

- Bug reports```bash

- Feature requests# Clone the repository

- Code improvementsgit clone https://github.com/yourusername/hypz-cli.git

- Documentation updatescd hypz-cli



Open an issue or PR on [GitHub](https://github.com/ysr-hameed/hypz-cli).# Install dependencies

npm install

## 📄 License

# Build

MIT License - see [LICENSE](LICENSE) file for details.npm run build



## 🌟 Why Developers Love Hypz# Link for local development

npm link

> "Hypz built my entire backend in 5 minutes. I just described what I needed." - *Alex K.*

# Run

> "The real-time visibility is game-changing. I see exactly what it's doing." - *Sarah M.*hypz start

"It actually understands my existing code and makes sensible changes." - David L.

Scripts

"Auto-fix saved me hours of debugging. It caught and fixed errors I didn't even see." - Maria R.

npm run build - Compile TypeScript to JavaScript

🚀 Get Started- `npm run dev` - Watch mode for development

npm run lint - Run ESLint

```bash- npm test - Run tests

npm install -g hypz-cli

hypz start## 📝 Configuration File

hypz "build something amazing"

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

That's all it takes. Let Hypz handle the heavy lifting while you focus on what matters - building great products.Example structure:

---```json

{

Built with ❤️ for developers who value their time. "llm": {

    "provider": "chatgpt",

Questions? Issues? Open an issue "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