Hubble

An agentic coding CLI engineered for autonomous, safe repository interaction. Hubble runs directly in your workspace to search, read, edit files, and execute shell commands using native tool calling under strict, user-configurable approval tiers.

It connects natively to Claude via Anthropic's Messages API (with prompt caching and extended thinking), any OpenAI-compatible gateway, or local models running through Ollama and LM Studio.

       ██╗  ██╗██╗   ██╗██████╗ ██████╗ ██╗     ███████╗
       ██║  ██║██║   ██║██╔══██╗██╔══██╗██║     ██╔════╝
       ███████║██║   ██║██████╔╝██████╔╝██║     █████╗  
       ██╔══██║██║   ██║██╔══██╗██╔══██╗██║     ██╔══╝  
       ██║  ██║╚██████╔╝██████╔╝██████╔╝███████╗███████╗
       ╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚══════╝

 > hubble "refactor the auth session handler to use JWT tokens"
 
   • read_file       src/auth/session.py (lines 1-84)
   • grep            "SessionStore" in src/
   • edit_file       src/auth/session.py [diff preview]
                     Allow edit? [y/n/a] y
   • shell           pytest tests/test_auth.py -v
                     Allow command? [y/n/a] a
   ✔ All 14 tests passing. Changes committed to branch.

Contents

• Highlights
• Installation
• Quickstart
• Execution Modes
• Safety & Permissions
• Sandboxed Shell Execution
• Tools
• Subagents & Model Teams
• Model Context Protocol (MCP)
• Lifecycle Hooks
• Custom Agents & Plugins
• Git Worktrees
• GitHub Actions Integration
• Model Routing & Telemetry
• Configuration
• CLI Reference
• Interactive REPL Reference
• Project Architecture
• License

Highlights

• Repository-Native Agent Loop: Reads, searches, and edits source trees with AST-aware line replacements, disk-freshness checks, and automated checkpoint snapshots for one-command rollback (/undo).
• Defense-in-Depth Sandboxing: OS-level command sandboxing via macOS Seatbelt (sandbox-exec), Linux bubblewrap, or ephemeral Docker containers with configurable CPU, memory, and network isolation.
• Provider Agnostic: Native integration with Anthropic Claude Messages API (prompt caching, thinking mode, native tool calling), any OpenAI-compatible API (AIHub, OpenAI, Groq, OpenRouter, Mistral, DeepSeek), and local LLMs (Ollama, LM Studio).
• Intelligent Dynamic Routing: Directs queries, lookups, and research subtasks to fast, low-cost models, escalating complex edits or failed operations to high-reasoning models automatically.
• Subagent Delegation & Teams: Dispatches focused research or implementation sub-agents in parallel across specialized models.
• Git Worktree Isolation: Spawns isolated scratch environments in .hubble/worktrees/ on dedicated branches to keep worktree experiments completely detached from the primary branch.
• Open Extensibility: Full support for Model Context Protocol (MCP) servers (stdio, Streamable HTTP, HTTP+SSE, automatic OAuth 2.0 authentication) and deterministic lifecycle hooks.
• Zero Secret Leakage: Strict file confinement blocks access to .env, credentials, SSH keys, and certificates.

Installation

Recommended: pipx

Install Hubble in an isolated environment accessible globally:

pipx install hubble-cli

To install directly using uv:

uv tool install hubble-cli

Standard pip

pip install --user hubble-cli

PATH Note: If hubble is not immediately found after a pip install, add the script directory to your system path automatically:

python -m hubble --add-to-path

Restart your terminal afterward.

Development Install

To run against a local git clone:

git clone https://github.com/Hamdayrabby/hubble-cli.git
cd hubble-cli
pip install -e .

Upgrading

pipx upgrade hubble-cli
# or: pip install -U hubble-cli

Hubble inspects PyPI for updates at most once daily. Set "update_check": false in your configuration to disable checks.

Quickstart

1. Launch in Any Repository

cd /path/to/your/project
hubble

On your initial run, if no API keys are detected, Hubble starts an interactive onboarding assistant to configure your credentials.

2. Manual Environment Configuration

Alternatively, supply credentials via .env in your project root or ~/.hubble/.env:

# OpenAI-compatible gateway (default)
HUBBLE_API_KEY="sk-..."
HUBBLE_BASE_URL="https://api.example.com/v1"

# Or native Anthropic Claude
ANTHROPIC_API_KEY="sk-ant-..."

API credentials added through the interactive REPL are stored in your OS credential store (Windows Credential Manager, macOS Keychain, or Linux Secret Service).

Execution Modes

Hubble operates both as an interactive REPL and as a non-interactive, scriptable command-line utility for automation and CI/CD pipelines.

Interactive REPL

hubble                                   # Launch interactive session
hubble "explain the authentication flow" # Launch REPL with an initial prompt
hubble -c                                # Continue the latest session in this directory
hubble -r                                # Interactively choose from previous sessions

Non-Interactive / Headless (-p)

Execute a task and return directly to the shell:

# Execute with specific approval policies and automated tool whitelists
hubble -p "fix the failing pytest suite" --permission-mode accept-edits --allow "shell(pytest*)"

# Pipe diffs or log files directly into Hubble
git diff | hubble -p "audit this diff for security regressions" --output-format json

# Stream JSON events for IDE integrations or orchestrators
hubble -p "run static analysis and report issues" --output-format stream-json

Stream-JSON Event Schema

When invoking --output-format stream-json, Hubble emits a newline-delimited JSON stream where each event includes a type discriminant:

• init: Session metadata, model configuration, and workspace paths.
• text: Delta stream of generated assistant response tokens.
• assistant: Consolidated model turn including token usage and requested tool invocations.
• tool_use: Start of a specific tool invocation with bound arguments.
• tool_result: Output payload returned by the executed tool.
• todos: Current state of the agent's task checklist.
• subagent_start / subagent_end: Lifecycle markers for delegated sub-agent tasks.
• result: Final turn summary and overall token accounting.

Multimodal Vision Inputs

Attach screenshots, architecture diagrams, or UI mockups:

# In headless mode
hubble -p "identify the CSS alignment defect" --image screenshot.png

# In interactive REPL
# 1. Type: "Analyze this layout @screenshot.png"
# 2. Or press Alt+V to paste an image directly from your clipboard

Safety & Permissions

Hubble enforces explicit boundaries to prevent unauthorized execution or unintended destructive modifications.

Permission Modes

Toggle modes dynamically with Shift+Tab during a session, or set via --permission-mode / /mode:

Interactive Approval Controls

When a file edit or shell command requires verification:

• y: Authorize the action once.
• a: Authorize the action for the entire session (all matching edits or commands matching the prefix, e.g., pytest*).
• n: Deny execution and provide immediate textual feedback to the agent.
• Ctrl+C: Abort the current model turn immediately.

Allow & Deny Rules

Rules can be defined in .hubble/settings.json or supplied via CLI flags:

hubble --allow "shell(pytest*)" --allow "shell(git status*)" --deny "shell(git push*)"

• Compound Command Protection: Allow rules never bypass shell chains (&&, ;, |, or redirects). For example, shell(git status*) will reject git status && rm -rf /.
• Precedence: Deny rules take precedence over allow rules.

Defensive Boundaries

• Workspace Confinement: Operations outside the workspace root are refused unless explicitly whitelisted via additional_dirs.
• Secret File Masking: Critical credential files (.env, *.pem, id_rsa, *.key) cannot be read, matched by grep, or attached to context.
• Freshness Verification: Files must be read immediately before an edit or overwrite is permitted; if the on-disk state changes, the write is aborted until re-read.
• Rollback Snapshotting: Every file modification is versioned locally. Run /undo to revert file modifications made during the preceding turn.

Sandboxed Shell Execution

OS-Native Sandboxing (macOS & Linux)

On macOS and Linux, shell execution operates under an operating system sandbox by default ("shell_sandbox": "auto"):

• macOS: Sandboxed via macOS Seatbelt (sandbox-exec).
• Linux: Sandboxed via bubblewrap (bwrap).

The sandbox permits system-wide reads while restricting write operations strictly to the workspace root, temp directories, and directories defined in sandbox_writable.

If a command requires broader access (such as installing global packages), the model requests an unsandboxed retry. This triggers an explicit user confirmation prompt regardless of permission mode (unless running in yolo).

Containerized Docker Sandbox (Cross-Platform)

For complete OS-agnostic isolation, execute all shell commands inside a dedicated Docker container:

# In the REPL
/sandbox docker

Configure Docker execution parameters in settings.json:

{
  "shell_sandbox": "docker",
  "sandbox_image": "python:3.12-slim",
  "sandbox_memory": "1g",
  "sandbox_cpus": "2",
  "sandbox_network": true
}

• The workspace directory is mounted to /workspace.
• Containers are instantiated per command and discarded immediately upon completion.
• Set "sandbox_network": false to isolate the container from outbound network traffic.

Tools

Hubble provides models with a curated set of deterministic tools:

Subagents & Model Teams

For complex tasks requiring broad exploratory research or isolated code changes, Hubble can delegate work to specialized sub-agents via invoke_subagent or task.

Pre-Configured Specialists

Hubble comes with out-of-the-box specialists that require zero configuration:

Triggering Policy & Gating

Uncontrolled subagent spawning wastes tokens and slows down execution. Hubble gives you explicit control over when subagents are permitted to spawn:

Configure the policy via:

• Interactive REPL: /subagent [auto|explicit|off]
• CLI Flag: hubble --subagent-policy explicit
• Settings: "subagent_policy": "explicit" in .hubble/settings.json

Dynamic Subagent Creation (define_subagent)

The model (or user) can dynamically define and persist new specialists on the fly:

define_subagent(
    name="api-docs-generator",
    description="Analyzes FastAPI/Flask route handlers and generates OpenAPI specs",
    system_prompt="You inspect routes, schemas, and docstrings to produce accurate OpenAPI specifications.",
    capability="read_only",
    scope="project" # or "user"
)

Once saved, the specialist is immediately available across all subagent tools and sessions.

Execution Isolation & Behavior

• inherit / none: Subagent runs directly in the parent workspace directory. Multiple read_only sub-agents triggered in a single turn execute in parallel.
• branch / share / worktree: Spins up the subagent inside a detached git worktree, committing changes to an isolated branch for review before merging.
• Token Budgets: Each subagent run can be constrained with an explicit token budget (e.g. budget: 500000) to prevent runaway context consumption.

Model Teams

Assign specific models to distinct sub-agent roles:

/team add aihub:ministral-8b-latest fast, for broad code search and discovery
/team add groq:llama-3.3-70b-versatile quick second opinions and diff reviews
/team add anthropic:claude-opus-5 careful, for deep architectural refactoring

Hubble evaluates recent model performance telemetry from /stats and routes subtasks accordingly (e.g., dispatching search tasks to fast models, and complex refactors to high-reasoning models).

Developer Lens & Design Language (LENS.md)

Avoid generic AI "boilerplate" or conflicting coding styles. True to Hubble's optics and deep-space telescope identity, Hubble views your repository through your personal Developer Lens (LENS.md) — enforcing your individual coding style, UI design language, aesthetic tokens, and architectural conventions across all code generation.

How the Lens Works

Lens files are discovered and injected with top priority into the system prompt:

• Global Lens: ~/.hubble/LENS.md (or ~/LENS.md) applies your universal style across every repository you open.
• Project Lens: <workspace>/LENS.md (or .hubble/lens.md, STYLE.md) configures repo-specific design languages and conventions.

When both exist, Hubble merges them so the project lens can specialize or override global rules.

Managing Your Lens (/lens)

• /lens (or /style): Inspect currently active lens files and preferences.
• /lens init: Scaffolds a starter LENS.md with sections for:
  • 🎨 UI & Design Language: Color palettes (e.g. HSL tailored tokens), typography pairings, spacing, component libraries.
  • 💻 Coding Style & Conventions: Guard clauses, early returns, typing rules, naming idioms.
  • 🏗️ Architecture & Boundaries: Modular file layout, state flow, dependency rules.
  • 🚫 Anti-Patterns: Explicit constraints on what the AI must never do.
• /lens add <preference>: Quickly append a micro-decision or new aesthetic rule to LENS.md.

Model Context Protocol (MCP)

Hubble natively supports the Model Context Protocol, exposing tools, resources, and prompt templates from external systems.

MCP Configuration

Define servers in .hubble/settings.json or ~/.hubble/settings.json:

{
  "mcp_servers": {
    "filesystem": {
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/share"]
    },
    "git": {
      "command": ["uvx", "mcp-server-git"]
    },
    "linear": {
      "url": "https://mcp.linear.app/mcp"
    },
    "internal-service": {
      "url": "https://mcp.internal.net/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_MCP_TOKEN}"
      }
    }
  }
}

• Environment Substitution: Variables written as ${VAR} in url, headers, and env are expanded from the environment.
• OAuth 2.0 Integration: Remote servers returning HTTP 401 are flagged for login. Run /mcp login <server> to initiate the browser-based authorization flow; tokens are stored in the OS credential store and refreshed automatically.
• Prompts as Slash Commands: Prompts exported by MCP servers are automatically exposed as REPL slash commands: /mcp__<server>__<prompt>.

Lifecycle Hooks

Hooks allow you to execute deterministic host commands at defined phases in the agent loop. Use them to enforce compliance, lint edited files, or inject contextual data.

Configuration

Add hooks to settings.json:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "shell", "command": "python .hubble/verify_command.py" }
    ],
    "PostToolUse": [
      { "matcher": "edit_file", "command": "python .hubble/lint_file.py" }
    ],
    "UserPromptSubmit": [
      { "command": "python .hubble/context_injector.py" }
    ],
    "Stop": [
      { "command": "python .hubble/require_tests.py" }
    ]
  }
}

Event Lifecycle

Hooks receive a JSON payload on stdin containing event details and communicate outcomes via exit codes or JSON on stdout:

• Exit non-zero: Blocks the action; stderr is passed back as the rejection rationale.
• Output {"decision": "block", "reason": "..."}: Blocks the action gracefully.
• Output {"additionalContext": "..."}: Appends data to prompts or tool outputs.

Custom Agents & Plugins

Custom Agents

Define persistent specialist personas by creating Markdown files in .hubble/agents/ (project) or ~/.hubble/agents/ (global):

---
name: test-engineer
description: Generates concise, thorough pytest suites. Use when implementing or fixing features.
tools: read_file, grep, glob, write_file, edit_file, shell
model: codestral-latest
capability: edit
---
You are an expert test engineer. Focus on boundary conditions, mock external dependencies,
and verify that test suites pass before concluding tasks.

Manage agents using the REPL:

• /agents: List installed agents and capabilities.
• /agents new <name>: Scaffold a new agent definition.

Plugins

Bundle commands, skills, custom agents, hooks, and MCP servers into redistributable packages:

my-team-plugin/
  plugin.json         # Plugin manifest defining hooks and MCP servers
  commands/*.md       # Custom slash commands
  agents/*.md         # Custom agent personas
  skills/*/SKILL.md   # Domain-specific procedural skills

Install and manage plugins:

/plugin install https://github.com/org/hubble-devops-plugin.git
/plugin list
/plugin disable my-team-plugin

Git Worktrees

Isolate hazardous refactors or run multiple parallel agent tasks without disturbing your active working tree:

# Launch Hubble inside a fresh worktree
hubble -w refactor-jwt

# Or manage worktrees interactively inside the REPL
/worktree new refactor-jwt      # Creates .hubble/worktrees/refactor-jwt on branch hubble/refactor-jwt
/worktree list                  # List active worktrees
/worktree switch <name>         # Switch workspace context
/worktree exit                  # Return to the primary repository checkout
/worktree remove refactor-jwt   # Delete worktree and prune metadata

Worktree directories are registered automatically in .git/info/exclude to prevent accidental inclusion in git commits.

GitHub Actions Integration

Deploy Hubble into your CI/CD workflow to perform automated pull request reviews or address issues:

/install-github

This generates .github/workflows/hubble.yml. Once configured with a HUBBLE_API_KEY secret:

• Pull Request Reviews: Hubble reviews every incoming pull request and provides inline feedback.
• Issue & PR Mentions: Mention @hubble <instruction> in any issue or PR comment to dispatch an agent. On pull requests, Hubble can apply modifications and push commits directly back to the branch.
• Security Scoping: Restricts triggering privileges to repository owners, collaborators, and members.

Model Routing & Telemetry

Tier-Based Model Routing

Optimize latency and inference expenses using /route:

/route fast aihub:ministral-8b-latest    # Small, rapid model for lookups and search
/route strong anthropic:claude-opus-5    # High-reasoning model for complex refactors
/route auto                              # Automatically selects optimal fast model via /stats

• Automatic Escalation: If the fast model produces malformed tool calls, fails repeatedly, or encounters empty responses, the task escalates to the strong model mid-turn.

Telemetry & Diagnostics (/stats)

Inspect local latency, reliability, token expenditure, and estimated cost:

# In the REPL
/stats

# From the shell
hubble --stats 30

Hubble records local analytics in ~/.hubble/stats.jsonl:

• Success rates per model.
• Latency and time-to-first-token (TTFT).
• HTTP failure codes (429, 503).
• Cost estimation (custom rates configurable via "model_prices").

Configuration

Settings are resolved using a layered hierarchy where subsequent layers override previous values:

1. Built-in defaults
2. Global configuration: ~/.hubble/settings.json
3. Repository configuration: .hubble/settings.json
4. Local overrides: .hubble/settings.local.json
5. CLI arguments

Example settings.json

{
  "model": "codestral-latest",
  "max_tokens": 8192,
  "context_window": 128000,
  "permission_mode": "default",
  "shell": "auto",
  "shell_sandbox": "auto",
  "additional_dirs": [],
  "permissions": {
    "allow": [
      "shell(pytest*)",
      "shell(git status*)",
      "shell(git diff*)"
    ],
    "deny": [
      "shell(git push*)",
      "edit_file(migrations/*)"
    ]
  },
  "mcp_servers": {},
  "hooks": {}
}

Repository Trust Model

To guard against malicious repositories with hostile .hubble/settings.json files:

• Repository settings cannot alter base_url or api_key.
• Critical parameters (permission_mode, shell_sandbox, hooks, and mcp_servers) require repository confirmation before execution.
• Trusted repositories are recorded in ~/.hubble/trusted_folders.json.

CLI Reference

usage: hubble [-h] [-p] [-c] [-r [ID]] [-m MODEL] [--provider PROVIDER]
              [--permission-mode {default,accept-edits,plan,yolo}] [--yolo]
              [--persona {code,debug,review,architect,chat}]
              [--subagent-policy {auto,explicit,off}]
              [--output-format {text,json,stream-json}] [--github]
              [--image FILE] [--max-turns MAX_TURNS] [--cwd CWD]
              [-w NAME] [--base-url BASE_URL] [--api-key API_KEY]
              [--allow RULE] [--deny RULE] [--no-session] [--quiet]
              [--test MODEL] [--stats [DAYS]] [--add-to-path] [-v]
              [prompt]

Options

Interactive REPL Reference

Slash Commands

Keyboard Shortcuts

• Shift+Tab: Cycle through permission modes.
• Alt+V: Paste image from system clipboard.
• @path: Autocomplete and attach file content, directory trees, or images.
• !command: Execute a shell command directly on the host machine.
• #note: Append a persistent development note to ./HUBBLE.md.
• Ctrl+C: Interrupt active model generation, tool execution, or clear the prompt. Press twice to exit.
• Ctrl+D: Terminate the REPL session cleanly.

Project Architecture

hubble/
├── main.py              CLI entrypoint, flag resolution, headless -p orchestration
├── repl.py              Interactive prompt_toolkit REPL, slash commands, @mentions
├── agent.py             Agent loop, compaction logic, subagent task dispatcher
├── ui.py                Rich console formatting, syntax highlighting, diffs, menus
├── indexer.py           Zero-dependency AST & regex symbol indexer (Python, TS/JS, Go, Rust)
├── provider.py          OpenAI-compatible client, SSE streaming, tool call parser
├── anthropic_provider.py Native Anthropic Messages API client (prompt caching, thinking)
├── tools.py             Workspace tool definitions, validation, snapshotting
├── sandbox.py           OS sandboxing (macOS Seatbelt, Linux bubblewrap, Docker)
├── permissions.py       Permission tiers, approval matching, allow/deny rules
├── mcp.py               Model Context Protocol client (stdio, HTTP, SSE)
├── mcp_oauth.py         OAuth 2.0 discovery, browser login, credential storage
├── hooks.py             Deterministic lifecycle hook runner and evaluator
├── subagents.py         Custom agent definition loader and validator
├── plugins.py           Plugin registry, loading, and isolation
├── worktree.py          Git worktree creation, branch switching, and lifecycle
├── router.py            Dynamic tier-based model routing engine
├── scanner.py           Background model verification and latency scanner
├── keystore.py          OS credential store integration (Keyring/SecretService)
├── settings.py          Layered configuration loader and repository trust manager
├── session.py           JSONL session serialization and persistence
└── prompts.py           System prompt templates, personas, and memory loaders

License

This project is licensed under the MIT License.