Metadata-Version: 2.4
Name: hypergolic
Version: 0.8.2
Summary: An AI-powered coding assistant
Requires-Python: >=3.14
Description-Content-Type: text/markdown
Requires-Dist: alembic>=1.18.4
Requires-Dist: anthropic[bedrock]>=0.84.0
Requires-Dist: certifi>=2025.0
Requires-Dist: fastapi>=0.135.1
Requires-Dist: pillow>=12.1.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pydantic-settings>=2.13.1
Requires-Dist: python-multipart>=0.0.22
Requires-Dist: rich>=14.3.3
Requires-Dist: ruff>=0.15.6
Requires-Dist: sqlalchemy>=2.0.48
Requires-Dist: ty>=0.0.23
Requires-Dist: uvicorn[standard]>=0.41.0
Requires-Dist: pywebview>=5.0
Requires-Dist: mcp>=1.26.0

# Hypergolic

A local, native AI coding assistant. Hypergolic runs as a desktop app on your machine, giving you a chat interface backed by an agentic loop with full access to your filesystem, shell, and git history.

Key capabilities:

- **Agentic tool loop** — Read, write, search, and edit files; run shell commands (with your approval); navigate git history; and manage directories.
- **Persistent knowledge graph** — Accumulates corrections, preferences, and project context in a local SQLite database and recalls them in future sessions.
- **Layered system prompt** — Compose behavior from a base prompt, a user-level prompt, and a per-project prompt. All are injected automatically.
- **Session continuity** — Conversations are persisted and resumable. Session context (working directory, git branch, recent commits) is injected at the start of each turn.
- **Model tier selection** — Choose between Haiku, Sonnet, and Opus per session.

## Installation

```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Hypergolic
uv tool install hypergolic
```

### Set environment variables

Hypergolic needs an API key and base URL for an Anthropic-compatible API:

```bash
export HYPERGOLIC_API_KEY="your-api-key"
export HYPERGOLIC_BASE_URL="https://api.anthropic.com"  # or your proxy/gateway URL
```

### Launch

```bash
h
```

This runs database migrations, seeds default knowledge tags, detects the current git project, starts the local server, and opens the native desktop window.

## Usage

Once launched, you'll see a three-panel layout:

- **Left sidebar** — File explorer, version control (git log + diffs), and knowledge graph browser.
- **Center** — Chat interface. Type a message, optionally attach files or images, and send.
- **Right sidebar** — File viewer for inspecting code the assistant is working with.

### How a turn works

1. You send a message.
2. Hypergolic assembles a system prompt (base + user + project + session context + knowledge), appends your message to the conversation history, and streams a response.
3. If Hypergolic invokes tools (reading files, editing code, running commands), those execute locally and results are fed back. The loop continues until a final text response is produced.
4. Shell commands require your explicit approval in the UI before executing.

### Available tools

| Tool | Description |
|------|-------------|
| `list_files` | List directory contents with glob filtering and depth limits |
| `read_files` | Read one or more files by path |
| `search_files` | Ripgrep-powered search across file contents |
| `edit_files` | Targeted find-and-replace edits |
| `write_files` | Create or overwrite files |
| `delete_files` | Delete files by path |
| `make_directory` | Create directories |
| `command` | Execute shell commands (requires approval) |
| `knowledge` | Create, search, tag, and manage persistent knowledge |

## Configuration

Hypergolic uses a layered configuration system. Settings are loaded from JSON config files and Markdown prompt files at two levels: user and project.

### Config files

| Path | Scope | Purpose |
|------|-------|---------|
| `~/.agents/config.json` | User | Database path, user-level MCP servers |
| `<repo>/.agents/config.json` | Project | Project name, project-level MCP servers |

Example `~/.agents/config.json`:

```json
{
  "db_path": "~/.agents/hypergolic.db",
  "prompt_path": "~/.agents/prompt.md",
  "mcp_servers": {}
}
```

### System prompt customization

The system prompt is assembled from multiple Markdown files, concatenated in order:

1. **Base prompt** — Built into the package at `src/hypergolic/prompts/base_prompt.md`. Defines the assistant's core identity and behavioral guidelines.
2. **User prompt** — `~/.agents/PROMPT.md`. Add your personal preferences, background, and global instructions here. This is injected for every session regardless of project.
3. **Project prompt** — `<git-repo-root>/.agents/PROMPT.md`. Add project-specific guidance: tech stack, conventions, validation steps, architectural constraints. This is injected only when working within that repository.
4. **Session context** — Auto-generated. Includes session ID, working directory, OS, git branch, and recent commits.
5. **Knowledge graph** — Auto-injected from the local database. Includes universal, user, project, and session-scoped knowledge items.

To customize behavior, create or edit the user and project prompt files. No special syntax is required — just write Markdown.

### Example `~/.agents/PROMPT.md`

```markdown
# User Preferences

I prefer uv over poetry for Python projects.
Always use pnpm, never npm or yarn.
I work primarily in Python and TypeScript.
```

### Example `<repo>/.agents/PROMPT.md`

```markdown
# Project Guidance

This is a Django 5.1 project using PostgreSQL.
Run `./bin/validate` after making changes to verify the build.
Never modify files in the `generated/` directory.
```

## Knowledge Graph

The knowledge graph is a persistent, tagged store of facts that the assistant builds up over time. It lives in your local SQLite database and is automatically queried and injected into the system prompt each turn.

### How it works

- When you correct the assistant or state a preference, it stores that as a knowledge item.
- Items are tagged (e.g., `code-style`, `tooling`, `correction`) and scoped (`universal`, `user`, `project`, `session`).
- Universal and user-scoped items are injected in every session. Project-scoped items only appear when you're working in that project's repository. Session-scoped items only appear in that session.
- You can browse, create, edit, and delete knowledge items from the Knowledge panel in the left sidebar.

### Default tags

`code-style` · `tooling` · `architecture` · `domain` · `team` · `workflow` · `debugging` · `preference` · `correction`

You can create custom tags and delete any of the defaults.

## Tips

- **Front-load project context.** Write a thorough `.agents/PROMPT.md` for each repository you work in. Include how to validate changes, what tools you use, and any architectural constraints. The more context the assistant has up front, the fewer corrections you'll need.
- **Correct early, correct once.** When the assistant does something you don't like, tell it directly. It will store the correction in the knowledge graph and apply it in future sessions.
- **Use model tiers strategically.** Haiku is fast and cheap for simple tasks. Sonnet is the default workhorse. Opus is for complex reasoning and architectural decisions. Pick the tier that fits the task.
- **Attach files and images.** You can drag files into the chat input. The assistant can read images (screenshots, diagrams) and use them as context.
- **Let it research first.** The assistant is most effective when it reads the relevant code before making changes. If it jumps to editing too quickly, tell it to explore first.
- **Review shell commands.** Commands require your approval for a reason. Read them before clicking approve, especially for destructive operations.
- **Prune your knowledge graph.** Over time, knowledge items can become stale. Periodically review the Knowledge panel and delete anything outdated.

## Development

To work on Hypergolic itself:

```bash
# Launch with auto UI rebuilds
HYPERGOLIC_DEV_MODE=true uv run h

# Run the full validation suite (type checking, linting, UI build, UI tests)
./bin/validate

# Run UI dev server separately (hot reload)
cd ui && pnpm run dev
```

The backend is Python (FastAPI + SQLAlchemy + Alembic), and the frontend is React (Redux Toolkit + Ant Design + React Router).

## License

MIT
