HighhX

HighhX is a developer automation CLI. Run highhx in a project and describe what you want. Everything HighhX does — a command you typed, a sentence, a workflow step, or a step the AI agent proposed — is an action from one catalog, run by one executor that rates its risk deterministically, asks when the risk calls for it, executes with timeouts and cancellation, verifies the result, records it and can undo it where that is possible.

HighhX Free — deterministic developer automation	The interactive session and the full developer CLI: plain language for known, fully specified requests, 61 actions (files, git, packages, docker, databases, services, browser, deployments, security, workflows, shell), workflows with rollback, resume and cancel, /plan + /approve, /undo, voice with local speech-to-text. No AI, no account.
HighhX Pro — deterministic automation + AI developer agent	The same session with the AI agent attached: open-ended requests, planning, repository-wide changes, debugging, refactoring, AI computer use — proposed as action graphs that the same executor validates, rates, approves and runs. Autonomous tasks: "fix the login bug and make sure all tests pass" runs until HighhX itself has verified the tests.

Run highhx in a terminal and describe what you want. Free and Pro share one interface and one execution platform: the same tools, safety policy, confirmations, verification and audit trail. Your plan only decides which capabilities the session has — the HighhX platform grants and enforces them. The AI only chooses actions; it never gets its own way to run them.

Documentation

Product specification (start here) · Architecture · Action engine · Safety model · Security · Free and Pro · Agent runtime · Automation · Voice · Observability · Plugin system · CLI reference (all commands) · Roadmap · Contributing

$ highhx doctor

HighhX Doctor

✓ macOS 15.2 arm64
✓ HighhX on Python 3.13.1
✓ git 2.47.1
✓ node 22.12.0
✓ python satisfies >=3.11 — declared in pyproject.toml
✓ Configuration valid
✓ Workflows valid — 7 workflow(s)
⚠ docker unavailable — required by this project
✗ Missing DATABASE_URL — profile development

Suggested actions
  → Install docker and make sure it is on PATH.
  → Set it with `highhx env set DATABASE_URL --profile development` or export it in your shell.

• Documentation
• Why HighhX
• Installation
• Quick start
• The interactive session
• HighhX Pro: the AI developer agent
• Commands
• Workflows
• Configuration
• Plugins
• Security model
• Development
• Contributing

Why HighhX

Most projects accumulate a pile of scripts, Makefile targets, README snippets and CI YAML that only half the team remembers. HighhX gives every project the same front door:

• Local-first CLI. Every Free command works without an account or network. History, logs and deployment state live in .highhx/ on your machine.
• An AI agent that uses your real tools (Pro). highhx agent works through HighhX's own commands and safety system — not a chatbot pasting shell snippets.
• Detects instead of asking. Python (pip/uv/poetry/pdm/pipenv), Node (npm/pnpm/yarn/bun), React, Next.js, Flutter/Dart, Java (Maven/Gradle), C/C++ (CMake/Make), Go, Rust, Docker, common databases and monorepos — from real manifests and lockfiles, not file extensions.
• Safe by default. Commands are classified as safe, normal, dangerous or critical. git push, rm -rf, DROP TABLE, production deploys and restores need approval; --dry-run previews anything; policies can make approvals non-bypassable even with --yes.
• A real workflow engine. YAML workflows with dependency graphs, parallel execution, conditions, variables, retries with backoff, timeouts, approvals and reusable workflows — validated before anything runs.
• Scriptable. Every command supports --json and meaningful exit codes.

Installation

HighhX needs Python 3.11+. It is developed and tested on macOS; Linux and Windows support is designed in (see docs/development.md) but not yet verified on those systems.

HighhXcli is not yet published on PyPI. Install it from a built wheel or from source.

# from a checkout of this repository
python -m pip install build && python -m build          # creates dist/highhxcli-*.whl
pipx install dist/highhxcli-*.whl                       # or: pip install dist/highhxcli-*.whl

# development install
python -m venv .venv && . .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Both highhx and highhxcli are installed as commands, and python -m highhx works too.

Runtime dependencies are deliberately small: click, rich and PyYAML. External tools (git, docker, kubectl, psql …) are used only when a feature needs them.

Quick start

cd your-project
highhx init            # detect the project, create .highhx/ (never overwrites without --force)
highhx doctor          # check tools, config, env vars, ports
highhx status          # dashboard: git, environment, services, recent runs
highhx test            # auto-detected test runner (pytest, vitest, jest, flutter, mvn, …)
highhx run ci          # run a workflow; parallel where dependencies allow
highhx run ci --dry-run
highhx history         # what ran, when, how long, exit codes
highhx logs            # output of the last execution (secrets redacted)

highhx init creates:

.highhx/
├── config.yaml          # commands, services, deploy targets, approvals …
├── environment.yaml     # declared variables and profiles (values live in .env files)
├── policies.yaml        # protected branches, forbidden files, rules
├── workflows/           # dev, test, build, ci, release, deploy, rollback
├── hooks/               # scripts for git hooks
├── state/               # local database (git-ignored)
└── logs/                # execution logs (git-ignored)

The interactive session

highhx with no arguments, in a terminal, opens the HighhX session (highhx agent opens the same one). Outside a terminal, and with --json or --quiet, it prints the help as before, so scripts and CI are unaffected.

$ highhx

  (the Knight)   HighhX v0.5.0
                 Developer command center
                 ~/code/shop
                 main • clean
                 Free • Local

❯ show git status

◉ highhx git status
✓ Working tree clean
✓ highhx git status (0.1s)

❯ Fix the failing tests

╭─ HighhX Pro capability ─────────────────────────────╮
│  AI code changes require HighhX Pro.                │
│                                                     │
│  Available locally, without AI:                     │
│  1  Run the tests         highhx test               │
│  2  Diagnose the project  highhx diagnose           │
│  3  Show recent logs      highhx logs               │
│                                                     │
│  [1-3] Continue locally    [p] View Pro             │
╰─────────────────────────────────────────────────────╯

• Plain language first. On Free, a deterministic resolver turns known, fully specified requests into actions — run the tests and then build, stop the backend, deploy staging, commit all changes with message "…", open localhost 3000 — using your project's services, targets and workflows as entities. It never guesses: open-ended requests show what HighhX Pro would do and the local actions that can do part of the job. On Pro the AI agent handles every request.
• Preview, approve, undo. /plan <request> shows each step with its risk; /approve runs exactly that plan; /undo reverts the last file changes; /retry re-runs a failed request; /resume and /cancel operate workflow runs.
• !command runs a shell command as an action (classified, approved by risk, audited — rm -rf / never runs); highhx <command> runs any HighhX command in the session.
• Input. ↑/↓ history (kept across sessions), line editing, \ at the end of a line or a """ block for multi-line input, Ctrl+C interrupts the running request, Ctrl+D exits.
• Status line. Free • Local, Free • Connected, Pro • Connected, Pro • Offline (cached) or … • Platform unavailable. Only a live answer from the platform attaches the AI agent. When the platform cannot be reached, local capabilities keep working and the session re-checks when a request needs the agent; if the gateway fails during a Pro request, the session says so and offers the local route for it.
• Deterministic means predictable. Free never calls a model or reads a provider API key. File names are never treated as websites (open main.py is not https://main.py), and changes are approved according to one risk table (docs/SAFETY_MODEL.md).
• Plan changes apply in place. Run highhx login (or /account after upgrading) inside the session and it re-checks your account: the AI agent attaches when the platform grants it, and detaches when it no longer does.
• Slash commands, grouped in /help: run (/plan /approve /deny /retry /run), review (/status /history /changes /undo /doctor), workflows (/workflows /workflow /resume /cancel), project (/init /context /tools /config /memory), account & AI (/login /account /pro /usage, and the agent's /model /mode), session (/voice /clear /help /quit). /status shows what is waiting on you and which command acts on it. See docs/CLI_REFERENCE.md.
• First run. The first session shows a short Getting started: /init, a first request, /plan + /approve, and /login for Pro.
• Voice. highhx voice or /voice on: push-to-talk with a local speech-to-text engine; transcripts are confirmed before they run (docs/VOICE.md).

HighhX Pro: the AI developer agent

$ highhx

     ▗█▖
     ▐▀▌
    ▗ ▄ ▖
   ▗▚▐█▌▞▖
  ▗▚█▐█▌█▞▖      HighhX v0.5.0
   ▟█▐█▌█▙       Developer command center
  ▐▐█▌█▐█▌▌      ~/code/shop
  █▗▜▌█▐▛▖█      main • clean
  █▐▙▘█▝▟▌█      Pro • Connected
  ▐▐▜▌▄▐▛▌▌
 ▗▝▐▐▌█▐▌▌▘▖
 █▙▝█▌█▐█▘▟█
▜▙▜█▖▘█▝▗█▛▟▛
 ▀█▟▀ █ ▀▙█▀
   ▀▌ █ ▐▀

Project   shop Python, FastAPI
AI        Connected HighhX (managed)

What would you like me to do? (/help for commands)

❯ run all the tests and fix whatever fails

╭─ Plan ───────────────────────────────────────────╮
│  1. Run the test suite                           │
│  2. Investigate the failures                     │
│  3. Fix the root cause                           │
│  4. Re-run tests, lint and type checks           │
╰─ Get the test suite green ───────────────────────╯
Proceed? [Y/n]

✓ Run tests — 3 tests failing (4.1s)
✓ Read src/shop/cart.py — 88 lines

╭─ ⚠ Action requires approval ─────────────────────╮
│  Edit src/shop/cart.py (+2 -1)                   │
╰──────────────────────────────────────────────────╯
  …diff…
Proceed? [y/N/a=always this session] y
✓ Edit src/shop/cart.py — +2 -1
✓ Run tests — Tests passing — 48 passed (pytest) (4.3s)
✓ Run checks — all checks passed

Fixed the discount rounding in `cart.total()` (it rounded before applying tax).
All 48 tests pass; lint and type checks are clean.

4 steps  ·  1 file changed (/undo)  ·  38.2k tokens  ·  41s

Ask for what you want in plain language — explain how this project works, find and fix the bugs, add authentication, find security issues, why is the application crashing?, prepare this project for release, deploy this. The agent inspects the project, proposes a plan for multi-step work, uses HighhX's capabilities as tools (code search and edits, tests, checks, fixers, builds, dependencies, git, security scans, doctor/diagnose/repair, workflows, deploy and rollback), verifies what it did and summarises it.

• Same safety system. Commands run through the HighhX engine: risk classification, policies.yaml, approvals and history. File edits show a diff and ask (unless you choose --mode auto-edit); pushes, deploys and rollbacks always ask; production deploys need typed confirmation. The agent cannot leave the project, read secret files or touch .git/. --mode read-only investigates without changing anything.
• Slash commands. Everything from the interactive session, plus /plan /model /mode /changes /undo.
• Sessions. Saved per project: highhx agent --continue, --resume ID, highhx agent sessions.
• Scriptable. highhx agent "…" outside a terminal (or with --json) handles one request and exits — --yes --mode auto-edit for unattended runs in CI.
• Providers. All Pro AI goes through the HighhX platform (authenticated, plan-checked, metered); choose the upstream — Anthropic, OpenAI or Gemini — with highhx account settings or /model. No provider key is needed on your machine.
• Kill switch. highhx agent stop (or Ctrl+C) cancels the model request, retries, running commands and their child processes immediately.
• Computer use. The agent observes browsers and apps semantically and chooses among valid actions; see docs/computer-use.md.

highhx login                 # browser sign-in (creates your account)
highhx account upgrade       # HighhX Pro checkout
highhx                       # interactive session (also: highhx agent)
highhx agent "why is the application crashing?"

Guides: docs/agent.md · docs/computer-use.md · docs/platform.md.

Commands

Full reference with every option: docs/commands.md.

Area	Commands
HighhX Pro	agent agent sessions agent models agent stop
Automation (no AI)	do computer status/open/observe/click/type/select/press/scroll/run computer browser start/stop
Account	login logout account account plans/usage/upgrade/billing/settings
Project	init status info dev start stop restart check
Code & tasks	run <workflow> exec <command> script <name> task <name> watch fix
Dependencies	deps deps install deps update deps outdated deps audit deps clean
Testing & build	test [--watch] [--coverage] [--changed] benchmark build clean package artifacts
Environment	env env check env set env profile env diff
Git & releases	git status/diff/branch/commit/sync/tag/history version changelog release publish
Deployment	deploy [target] deploy status deploy logs rollback environments
Security	security security scan/secrets/deps/config/report
Containers & data	docker up/down/logs services ports db status/migrate/seed/backup/restore
Workflows & automation	workflow list/validate/create/graph schedule hook trigger watchers
Observability	logs [--follow] history [id] audit report trace
Extensibility & team	plugin list/install/remove/update/search/trust config policy workspace profile
Diagnostics	doctor diagnose repair debug

Global options (work before or after the command): --json, --dry-run, --yes/-y, --force, --quiet/-q, --verbose/-v, --debug, --no-color, --cwd/-C DIR, --config-profile NAME, --version, --help.

A few examples:

highhx exec -- pytest -q                 # run anything with env profile, risk check, history
highhx exec --timeout 30s --retry 3 -- ./flaky.sh
highhx test --changed                    # only tests related to files changed since HEAD
highhx deps update                       # shows what will change, then asks
highhx env set DATABASE_URL              # prompts without echo; value never printed again
highhx release                           # version from Conventional Commits, changelog, tag
highhx deploy staging --version 1.4.0    # preflight → approval → deploy → health check
highhx rollback staging                  # restore the previous successful deployment
highhx security --fail-on high           # exit 9 if high/critical findings
highhx workflow graph ci --format mermaid
highhx status --json | jq .git.branch

Workflows

Workflows are YAML files in .highhx/workflows/. Full reference: docs/workflows.md · JSON Schema: schemas/workflow.schema.json.

name: production

settings:
  fail_fast: true
  max_parallel: 4
  timeout: 30m

steps:
  - id: test
    run: pytest

  - id: lint
    run: ruff check .

  - id: build
    run: docker build -t myapp .
    depends_on: [test, lint]          # test and lint run in parallel first

  - id: deploy
    run: ./deploy.sh ${{ steps.build.outputs.tag }}
    depends_on: [build]
    approval: true                    # asks before running
    retry:
      attempts: 3
      delay: 10s                      # exponential backoff: 10s, 20s …

  - id: notify
    run: ./notify.sh "deploy failed"
    depends_on: [deploy]
    if: failure()

A step never starts before every step in its depends_on succeeded. Steps whose dependencies are satisfied run in parallel (up to max_parallel). Also supported: if: conditions, ${{ }} variables (env, vars, inputs, steps.<id>.outputs), step outputs, continue_on_error, per-step timeout/cwd/env, reusable workflows (uses: other-workflow with with: inputs), and on: event triggers.

highhx workflow validate catches circular and missing dependencies, duplicate ids, unknown fields, bad expressions, references to steps that are not dependencies, unparsable commands, impossible steps and risky commands without approval — before anything runs.

Configuration

.highhx/config.yaml is validated strictly (unknown keys are errors with "did you mean" suggestions). Reference: docs/configuration.md · JSON Schema: schemas/config.schema.json.

version: 1
project:
  name: shop
commands:              # override anything HighhX detected
  test: uv run pytest
  dev: uv run uvicorn app.main:app --reload
services:              # highhx start / stop / services
  api:
    command: uv run uvicorn app.main:app --port 8000
    port: 8000
    health: {url: http://127.0.0.1:8000/health}
deploy:
  default: staging
  targets:
    staging:
      type: ssh                       # local | docker | ssh | kubernetes | terraform | plugin:<name>
      host: deploy@staging.example.com
      command: ./deploy.sh {{ version }}
      rollback_command: ./deploy.sh {{ previous_version }}
      health_check: {url: https://staging.example.com/health}
approvals:
  auto_approve: normal                # never prompt at or below this risk
  yes_max_risk: critical              # the highest risk --yes may approve

Config profiles (.highhx/profiles/ci.yaml) overlay the config with --config-profile ci. Environment profiles (development/staging/production) are separate and live in .highhx/environment.yaml plus your .env files — see highhx env --help.

Plugins

Plugins add commands, workflows, templates, detectors and deployment backends. Guide: docs/plugins.md.

# my-plugin/highhx-plugin.yaml
name: greet
version: 1.0.0
api_version: 1
permissions: [commands]
contributes:
  commands:
    - name: greet
      run: echo "hello"
  workflows: [workflows]

highhx plugin install ./my-plugin      # or a git URL, or a name from plugins.index
highhx greet

Declarative contributions run as subprocesses with an isolated environment. Python code plugins run only when plugins.allow_code: true and you trusted those exact files (by SHA-256) with highhx plugin install or highhx plugin trust. Trust is stored in your user data directory, so a cloned repository cannot enable its own plugin code.

Security model

Details: docs/SECURITY.md.

• Approvals. Every command is classified (safe / normal / dangerous / critical). Anything above approvals.auto_approve asks; critical actions require typing a word. Without a terminal, HighhX denies instead of guessing. --yes approves up to approvals.yes_max_risk, never beyond, and never for non-bypassable rules (e.g. rm -rf /, terraform destroy, policy rules with bypassable: false).
• Policies. .highhx/policies.yaml can deny commands/actions, require approval, protect branches, forbid committed files and require a clean tree for releases/deploys.
• Secrets. Secret values are never printed: env masks them, logs and history are redacted (known secret values plus token patterns), and security secrets reports file/line/type only. New .env files get owner-only permissions and are git-ignored.
• The agent. Uses the same engine, policies and approvals as you do, plus path confinement, secret-file protection and redaction of everything sent to the model. Agent actions have policy names (agent:write, agent:exec, agent:deploy:<target> …) so policies.yaml can restrict or forbid them.
• No claims. highhx security reports concrete findings from local checks. An empty report does not mean a project is secure, and HighhX never says it is.

Report vulnerabilities in HighhX itself as described in SECURITY.md.

Development

pip install -e ".[dev]" -e "./server[dev]"
pytest                 # CLI: unit, integration, security and end-to-end tests
(cd server && pytest)  # platform API + live CLI ↔ platform integration tests
ruff check . && ruff format --check .
mypy                   # strict typing of src/highhx

The HighhX Platform backend lives in server/.

Architecture: docs/ARCHITECTURE.md · Development guide: docs/development.md · Troubleshooting: docs/troubleshooting.md.

Contributing

Contributions are welcome — see CONTRIBUTING.md and the Code of Conduct. Please open an issue before large changes.

License

MIT — see LICENSE.