Metadata-Version: 2.4
Name: hypergolic
Version: 0.5.0
Summary: Add your description here
Requires-Python: ==3.14.2
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic==0.76.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pyobjc-framework-applicationservices>=12.1
Requires-Dist: pyobjc-framework-quartz>=12.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.32.5
Requires-Dist: textual>=7.3.0
Requires-Dist: tiktoken>=0.12.0
Requires-Dist: typer>=0.21.1
Requires-Dist: playwright>=1.52.0
Dynamic: license-file

# 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
- Session branches 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:

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

```bash
uv tool install hypergolic
```

This installs `h` as a globally available command.

## Usage

Navigate to any git repository and run:

```bash
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 on a session branch, making changes you can review
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.md` in your repo root for project-specific instructions.

## Architecture

Hypergolic creates a session branch for each coding session. This keeps your work organized and allows you to review changes before merging. After code review, changes can be merged back into the original branch.

## Built With

- Python 3.14+
- [Anthropic Claude API](https://www.anthropic.com/)
- [Textual](https://textual.textualize.io/) for the TUI
- [uv](https://docs.astral.sh/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.
