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


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.
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
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`
wget -qO- https://raw.githubusercontent.com/ysr-hameed/hypz-cli/main/install.sh | bash
bash
npm install -g hypz-cli
``### NPM Install
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
npm install
`bashnpm run build
hypz`
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
``
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
to start chatting - no prompts, instant conversation- π Real-time Streaming: See code generate live with streaming support for all major LLM providers
- π 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
- 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
``
``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
π Applying fixes...
β Fixed all TypeScript errors
β All tests passingThe ultimate hands-off experience:
``
``bash
`bashI will now autonomously:
hypz config 1οΈβ£ Create a detailed plan
` 2οΈβ£ Generate all code files
3οΈβ£ Install dependencies
5οΈβ£ Auto-fix any errors
`bash
hypz startπ PHASE 1: Creating Detailed Plan
`β Plan created!
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
β Done
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!
``
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
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...
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
``
- 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`
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"
- 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"
`bash### Fix and Improve
hypz [task]`bash
hypz run "Add error handling and input validation to the existing API"
hypz start
hypz config### Latest AI Models
, gpt-4o, gpt-4o-minihypz --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
, 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
β "make an app"
β "create a blog API with Express, MongoDB, JWT auth"- OpenAI: https://platform.openai.com/api-keys
- Anthropic: https://console.anthropic.com/
β "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/
β 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
Hypz automatically:
`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
``
``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"
``
``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
`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:
- File Diffs: Line-by-line changes with ++ (added) and -- (removed) indicators
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
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
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
`bashhypz-cli/
hypz configβ βββ commands/ # CLI commands
β β βββ start.ts # Setup flow
hypz startβ β βββ config.ts # Configuration management
`β βββ llm/
β β βββ client.ts # LLM provider clients
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/
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.`
- 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
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
MIT License - see LICENSE file for details.npm run build
npm link
> "Hypz built my entire backend in 5 minutes. I just described what I needed." - Alex K.
> "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._
> "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
- 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"
}
`
Contributions are welcome! Please feel free to submit a Pull Request.
MIT License - see LICENSE file for details
Run hypz start to set up your LLM provider.
- Verify your API key is correct
- Check your internet connection
- Ensure you have credits/quota remaining with your provider
- Hypz will automatically attempt to fix most errors
- Check that required tools (npm, node, etc.) are installed
- Review the error output for specific issues
- [ ] Project templates
- [ ] Git integration
- [ ] Multi-language support
- [ ] Team collaboration features
- [ ] Custom agent personalities
- [ ] Plugin system
For issues, questions, or suggestions, please open an issue on GitHub.
---
Made with β€οΈ by the Hypz team
``