hypergolic 0.3.4

Add your description here

Hypergolic

A powerful AI coding assistant with command-line tool access for macOS.

Features

• Execute shell commands on macOS
• Read and write files with surgical precision
• Navigate directories and explore projects
• Screenshot capture for visual context
• Code review integration for quality assurance
• Git worktree isolation for safe code modifications
• Multi-layered prompt system for personalized behavior

Installation

1. Configure Environment Variables

Hypergolic requires three environment variables to connect to your LLM provider:

export HYPERGOLIC_API_KEY="your-api-key"
export HYPERGOLIC_BASE_URL="https://api.anthropic.com"
export HYPERGOLIC_MODEL="claude-sonnet-4-20250514"

Add these to your shell profile (~/.zshrc, ~/.bashrc, etc.) for persistence.

2. Install with uv

uv tool install hypergolic

This installs h as a globally available command.

Usage

Navigate to any git repository and run:

h

This launches an interactive TUI where you can chat with the AI assistant. The assistant can:

• Read and modify files in your project
• Run shell commands
• Search through codebases
• Take screenshots for visual debugging
• Commit changes and request code reviews

Workflow

1. Start a session — Run h from your project directory
2. Describe your task — The assistant will explore your codebase and implement changes
3. Review changes — The assistant works in an isolated git worktree, keeping your working directory clean
4. Merge when ready — After code review, changes merge back to your original branch

Getting Started Tips

Be Specific

The more context you provide, the better the results. Instead of "fix the bug", try "the login form submits twice when clicking the button rapidly — add debouncing".

Let It Explore

The assistant works best when it can read existing code before making changes. If it asks to explore your codebase first, let it.

Use Screenshots

For UI issues, the assistant can take screenshots. Just mention "take a screenshot" or describe what you're seeing visually.

Customize Behavior

Create ~/.hypergolic/user_prompt.md for personal preferences that apply to all projects, or .agents/project_prompt.md in your repo for project-specific instructions.

Trust the Worktree

All changes happen in an isolated git worktree. Your working directory stays untouched until you explicitly merge. Feel free to experiment.

Architecture

Hypergolic uses an ephemeral git worktree system for safe code modifications. Each session gets its own isolated branch, allowing the AI to make changes without affecting your working directory. After code review, changes can be merged back into the original branch.

Built With

• Python 3.14+
• Anthropic Claude API
• Textual for the TUI
• uv for dependency management

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT License - See LICENSE file for details.