hypergolic 0.3.1__tar.gz

hypergolic-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Townley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hypergolic-0.3.1/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: hypergolic
+Version: 0.3.1
+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: requests>=2.32.5
+Requires-Dist: textual>=7.3.0
+Requires-Dist: tiktoken>=0.12.0
+Requires-Dist: typer>=0.21.1
+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
+- 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:
+
+```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 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](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.

hypergolic-0.3.1/README.md

@@ -0,0 +1,94 @@
+# 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:
+
+```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 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](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.

hypergolic-0.3.1/hypergolic/__init__.py

@@ -0,0 +1,3 @@
+from hypergolic.tui.app import HypergolicApp
+
+__all__ = ["HypergolicApp"]

hypergolic-0.3.1/hypergolic/agents.py

@@ -0,0 +1,94 @@
+from typing import cast
+
+from anthropic.types import MessageParam, ToolResultBlockParam, ToolUseBlock
+
+
+def find_tool_use_ids_in_message(message: MessageParam) -> set[str]:
+    tool_ids: set[str] = set()
+    content = message.get("content", [])
+
+    if not isinstance(content, list):
+        return tool_ids
+
+    for block in content:
+        if isinstance(block, dict) and block.get("type") == "tool_use":
+            tool_id = block.get("id")
+            if tool_id:
+                tool_ids.add(tool_id)
+        elif isinstance(block, ToolUseBlock):
+            tool_ids.add(block.id)
+
+    return tool_ids
+
+
+def find_tool_result_ids_in_message(message: MessageParam) -> set[str]:
+    result_ids: set[str] = set()
+    content = message.get("content", [])
+
+    if not isinstance(content, list):
+        return result_ids
+
+    for block in content:
+        if isinstance(block, dict) and block.get("type") == "tool_result":
+            tool_use_id = block.get("tool_use_id")
+            if tool_use_id:
+                result_ids.add(tool_use_id)
+
+    return result_ids
+
+
+def find_incomplete_tool_uses(messages: list[MessageParam]) -> set[str]:
+    all_tool_use_ids: set[str] = set()
+    all_tool_result_ids: set[str] = set()
+
+    for message in messages:
+        role = message.get("role")
+        if role == "assistant":
+            all_tool_use_ids.update(find_tool_use_ids_in_message(message))
+        elif role == "user":
+            all_tool_result_ids.update(find_tool_result_ids_in_message(message))
+
+    return all_tool_use_ids - all_tool_result_ids
+
+
+def create_interrupt_tool_results(
+    incomplete_tool_ids: set[str],
+) -> list[ToolResultBlockParam]:
+    return [
+        {
+            "type": "tool_result",
+            "tool_use_id": tool_id,
+            "content": "Tool execution was interrupted by user",
+            "is_error": True,
+        }
+        for tool_id in incomplete_tool_ids
+    ]
+
+
+def create_interrupt_user_message(user_text: str) -> MessageParam:
+    interrupt_notice = (
+        "[USER INTERRUPT] The user has interrupted your previous response. "
+        "Any tool calls that were in progress have been cancelled. "
+        "Please acknowledge the interruption and address the user's new message:\n\n"
+    )
+
+    return {
+        "role": "user",
+        "content": [{"type": "text", "text": interrupt_notice + user_text}],
+    }
+
+
+def prepare_interrupted_history(
+    messages: list[MessageParam],
+    interrupt_message: str,
+) -> list[MessageParam]:
+    result: list[MessageParam] = list(messages)
+    incomplete_ids = find_incomplete_tool_uses(result)
+
+    if incomplete_ids:
+        error_results = create_interrupt_tool_results(incomplete_ids)
+        error_message = cast(MessageParam, {"role": "user", "content": error_results})
+        result.append(error_message)
+
+    result.append(create_interrupt_user_message(interrupt_message))
+    return result

hypergolic-0.3.1/hypergolic/app/constants.py

@@ -0,0 +1 @@
+SESSION_WORKTREE_PREFIX = ".agent-worktree-"

hypergolic-0.3.1/hypergolic/app/crash_logs.py

@@ -0,0 +1,45 @@
+import sys
+import traceback
+from datetime import datetime
+from pathlib import Path
+
+
+def save_crash_log(exc_type, exc_value, exc_tb) -> None:
+    """Save crash information to the error log file.
+
+    Args:
+        exc_type: The exception type.
+        exc_value: The exception instance.
+        exc_tb: The traceback object.
+    """
+    log_path = get_crash_log_path()
+
+    # Ensure the log directory exists
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Format the crash log entry
+    timestamp = datetime.now().isoformat()
+    tb_lines = traceback.format_exception(exc_type, exc_value, exc_tb)
+    tb_str = "".join(tb_lines)
+
+    crash_entry = f"""
+================================================================================
+CRASH REPORT: {timestamp}
+================================================================================
+Exception Type: {exc_type.__name__}
+Exception Message: {exc_value}
+
+Traceback:
+{tb_str}
+"""
+
+    # Append to the log file
+    with open(log_path, "a", encoding="utf-8") as f:
+        f.write(crash_entry)
+
+    print(f"\nCrash logged to: {log_path}", file=sys.stderr)
+
+
+def get_crash_log_path() -> Path:
+    """Get the path to the crash log file."""
+    return Path.home() / ".hypergolic" / "logs" / "error.log"

hypergolic-0.3.1/hypergolic/app/entrypoint.py

@@ -0,0 +1,33 @@
+import sys
+
+from hypergolic.app.crash_logs import save_crash_log
+from hypergolic.app.lifespan import HypergolicLifespan
+from hypergolic.app.session_context import build_session_context
+from hypergolic.config import HypergolicConfig
+from hypergolic.tui.app import HypergolicApp
+
+
+def main():
+    try:
+        session_context = build_session_context()
+        config = HypergolicConfig()
+
+        with HypergolicLifespan(session_context):
+            app = HypergolicApp(session_context, config)
+            app.run()
+    except KeyboardInterrupt:
+        # Normal exit via Ctrl+C, don't log as crash
+        sys.exit(0)
+    except Exception:
+        # Log the crash (but don't let logging failures mask the original error)
+        try:
+            save_crash_log(*sys.exc_info())
+        except Exception:
+            pass  # Silently ignore logging failures
+
+        # Re-raise so the user sees the error and gets appropriate exit code
+        raise
+
+
+if __name__ == "__main__":
+    main()

hypergolic-0.3.1/hypergolic/app/lifespan.py

@@ -0,0 +1,51 @@
+from contextlib import contextmanager
+
+from hypergolic.app.session_context import SessionContext
+from hypergolic.app.version_control import (
+    BranchCleanupResult,
+    cleanup_agent_branch,
+    create_agent_branch,
+    create_worktree,
+    remove_worktree,
+    stash_dirty_branch,
+    unstash_dirty_branch,
+)
+
+
+@contextmanager
+def HypergolicLifespan(session_context: SessionContext, merge_on_exit: bool = False):
+    start(session_context)
+    try:
+        yield
+    finally:
+        end(session_context, merge_on_exit=merge_on_exit)
+
+
+def start(session_context: SessionContext):
+    print("Starting session...")
+    stash_dirty_branch(session_context)
+    create_agent_branch(session_context)
+    create_worktree(session_context)
+
+
+def end(session_context: SessionContext, merge_on_exit: bool = False):
+    print("Ending session...")
+    remove_worktree(session_context)
+
+    result = cleanup_agent_branch(session_context, merge_if_changes=merge_on_exit)
+
+    match result:
+        case BranchCleanupResult.DELETED:
+            print(f"Cleaned up empty branch: {session_context.agent_branch}")
+        case BranchCleanupResult.MERGED:
+            print(
+                f"✅ Merged {session_context.agent_branch} into {session_context.original_branch}"
+            )
+        case BranchCleanupResult.PRESERVED:
+            print(f"⚠️  Branch preserved with changes: {session_context.agent_branch}")
+            print(f"   To merge: git merge {session_context.agent_branch}")
+            print(f"   To delete: git branch -D {session_context.agent_branch}")
+        case BranchCleanupResult.NOT_FOUND:
+            pass  # Branch was already cleaned up somehow
+
+    unstash_dirty_branch(session_context)

hypergolic-0.3.1/hypergolic/app/session_context.py

@@ -0,0 +1,70 @@
+import subprocess
+import uuid
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from hypergolic.app.constants import SESSION_WORKTREE_PREFIX
+from hypergolic.tools.common import perform_command
+
+
+class SessionContext(BaseModel):
+    agent_branch: str
+    base_commit: str
+    original_branch: str
+    cwd: Path
+    branch_dirty: bool
+    git_root: Path
+    worktree_path: Path
+    project_name: str
+    remote_url: str | None = None
+
+
+def build_session_context() -> SessionContext:
+    original_branch = perform_command(["git", "branch", "--show-current"])
+    git_root = perform_command(["git", "rev-parse", "--show-toplevel"])
+    git_root_path = Path(git_root)
+    session_id = uuid.uuid4().hex[:8]
+    agent_branch = f"agent/session-{session_id}"
+    project_name = git_root_path.name
+    worktree_path = (
+        git_root_path.parent / f"{SESSION_WORKTREE_PREFIX}{project_name}-{session_id}"
+    )
+
+    staged_changes = run_subprocess(["git", "diff", "--cached", "--quiet"])
+    unstaged_changes = run_subprocess(["git", "diff", "--quiet"])
+    base_commit = perform_command(["git", "rev-parse", "HEAD"])
+    branch_dirty = staged_changes.returncode != 0 or unstaged_changes.returncode != 0
+
+    remote_url = get_remote_url()
+
+    return SessionContext(
+        agent_branch=agent_branch,
+        base_commit=base_commit,
+        branch_dirty=branch_dirty,
+        original_branch=original_branch,
+        cwd=Path.cwd(),
+        git_root=Path(git_root),
+        worktree_path=worktree_path,
+        project_name=project_name,
+        remote_url=remote_url,
+    )
+
+
+def get_remote_url() -> str | None:
+    result = run_subprocess(["git", "remote", "get-url", "origin"])
+    if result.returncode == 0:
+        url = result.stdout.strip()
+        if url:
+            return url
+    return None
+
+
+def run_subprocess(parts: list[str]) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        parts,
+        cwd=Path.cwd(),
+        capture_output=True,
+        text=True,
+        check=False,
+    )