🚀 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:

$3

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

bash

npm install -g hypz-cli

``### NPM Install

$3

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

$3

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

$3

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

``bash- 🔧 Terminal Integration: Runs real commands and shows actual output

$ 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)

``bash

→ 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

$3

- 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

$3

``

``bash

$ 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...

$3

✓ Fixed all TypeScript errors

✓ All tests passingThe ultimate hands-off experience:

``

``bash

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

$3

`bashI will now autonomously:

hypz config 1️⃣ Create a detailed plan

` 2️⃣ Generate all code files

3️⃣ Install dependencies

$3

5️⃣ Auto-fix any errors

`bash

hypz start📋 PHASE 1: Creating Detailed Plan

`✓ Plan created!

$3

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

$3

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!

``

$3

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

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...

$3

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

$3

$3

- 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`

$3

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"

$3

- 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

$3

❌ "make an app"

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

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

$3

❌ "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/

$3

✅ 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

$3

📊 Real-World Examples

Hypz automatically:

$3

`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

``

$3

$3

``bashWhen you report an issue:

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"

``

$3

``bashHypz will:

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

$3

`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

$3

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 for more details.

4. Writes application code

5. Adds tests### Smart Code Generation

6. Runs and verifies

- Generates complete, production-ready code

$3

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

$3

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

$3

`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

$3

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/

$3

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

$3

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.# Install dependencies

npm install

📄 License

Build

MIT License - see 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._

$3

> "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

$3

Run hypz start to set up your LLM provider.

$3

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

$3

- 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
``