Metadata-Version: 2.4
Name: hypergolic
Version: 0.8.4
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: typer>=0.15
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** — Files, shell, git, browser automation, and more. The assistant picks the right tools for the job; dangerous operations like shell commands require your explicit approval.
- **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) is injected at the start of each turn.
- **Skills and roles** — Activate specialized expertise (debugging, frontend, product thinking, etc.) on demand to shape the assistant's behavior for different tasks.
- **MCP integration** — Connect external tool servers via the Model Context Protocol for project-specific or personal tooling.

## Requirements

- **Python 3.14+**
- **macOS** (primary support; Linux may work but is untested)
- [uv](https://docs.astral.sh/uv/) for installation

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

You can get an API key at [console.anthropic.com](https://console.anthropic.com/).

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

## Quick Start

1. **Open a project.** `cd` into a git repository and run `h`.
2. **Ask it something.** Try: *"Read the README and summarize what this project does."* The assistant will use its tools to explore your repo.
3. **Watch it work.** You'll see tool calls (file reads, searches) stream in real time. If it needs to run a shell command, you'll be prompted to approve it.
4. **Correct it.** If it does something you don't like, say so. It will store the correction and remember it in future sessions.
5. **Set up your prompt.** Create `~/.agents/PROMPT.md` with your preferences, and `<repo>/.agents/PROMPT.md` with project-specific guidance. These are injected into every conversation automatically.

Keyboard shortcuts and navigation help are available in the **Help** sidebar panel.

An interactive onboarding experience is coming soon.

## 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, MCP servers, custom tools, skills, roles |
| `<repo>/.agents/config.json` | Project | Project name, MCP servers, custom tools, skills, roles |

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

```json
{
  "db_path": "~/.agents/hypergolicV4.db",
  "mcp_servers": {},
  "tools": [],
  "skills": [],
  "roles": []
}
```

### System prompt customization

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

1. **Role prompt** — The active role's prompt. Defaults to the built-in base prompt at `src/hypergolic/prompts/base_prompt.md`.
2. **User prompt** — `~/.agents/PROMPT.md`. Personal preferences, background, and global instructions. Injected in every session.
3. **Project prompt** — `<git-repo-root>/.agents/PROMPT.md`. Project-specific guidance: tech stack, conventions, validation steps. Injected only when working within that repository.
4. **User-project prompt** — Optional. Configured via `~/.agents/config.json` under `projects[].prompt_path`. For per-project guidance you don't want to commit to the repo.
5. **Session context** — Auto-generated. Includes session ID, working directory, OS, and git branch.
6. **Active skills** — Prompt content from any skills activated during the session.

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