hive-ide
An agent-aware tmux workspace for running coding agents across multiple sessions.
Status: stable. Version 1.x follows semantic versioning for its public interfaces.
Requirements
Unix (Linux/macOS), tmux, and Python 3.10+.
Install
macOS:
brew install pipx
pipx ensurepath
pipx install hive-ide
hive-ide open
Linux:
python3 -m pip install --user --upgrade hive-ide
hive-ide open
If your Python reports an externally managed environment, use pipx install hive-ide instead. pipx is the recommended install method for CLI app users
because it keeps hive-ide in its own environment while exposing the command on
PATH.
Bundled drivers are claude, codex, antigravity, and term. State is user-local and
directory-scoped. Agent drivers require their corresponding local command; term opens a
regular shell. On first open, hive-ide creates a default session for the current directory.
It uses term by default so the IDE opens without any agent installed. Set a configured
default driver or pass --driver=codex|claude|antigravity when you want an agent session.
An existing Git worktree is just a session working directory. The IDE attaches to it but never creates, merges, or removes it:
hive-ide open --driver=codex --working-dir=../project-feature
hive-ide working-dir-set --session-id=<ID> --working-dir=../project-feature
The sidebar marks linked worktrees as clean, modified, missing, or unknown.
Reopen the current session's plan or resume its recorded agent conversation:
hive-ide plan
hive-ide chat
Both commands use HIVE_IDE_SESSION_ID inside the frame, or accept
--session-id=<ID>. They target the session pane when its frame is running and
otherwise open in the current terminal.
Inside the tmux frame, press the new-session shortcut, enter an IDE label, choose
Claude or Codex, flip the bottom mode from new to adopt existing, then type to
filter and select the conversation to adopt. The same adoption backend is available
from the CLI for automation:
hive-ide adopt --driver=claude
hive-ide adopt --driver=codex
hive-ide open
To create one IDE session from a known or most recent conversation:
hive-ide create --name="FEATURE" --driver=claude --adopt --reference=<ID>
hive-ide create --name="FEATURE" --driver=codex --adopt --reference=<ID>
Local settings live in ~/.config/hive-ide/config.json (or HIVE_IDE_CONFIG).
The plan editor accepts any command string or argv list. Resolution is configured
editor, HIVE_IDE_EDITOR, micro when installed, then less:
{
"editor": "nvim --clean",
"keys": {
"prefix": "C-a",
"bindings": {"next": "n", "previous": "p", "error": null}
},
"diagnostics": {
"relayout_trace": false
},
"sidebar": {
"state": "activity",
"slots": ["plan", "checkout", "ci"],
"providers": {
"ci": {
"region": "slot",
"source": "session",
"path": ["host", "ci", "state"],
"icons": {"passing": "✓", "failing": "❌"}
}
},
"icons": {
"drivers": {"codex": "C"},
"providers": {"checkout": {"live": "W"}}
}
}
}
The right-side plan pane is a monitor by default. When the editor is micro, the pane
opens as micro -readonly true <path>; for vim/nvim/vi/gvim it opens with -R;
unknown editors are launched without extra flags. Plan, task, and scratchpad popups remain
editable because they are deliberate edit actions.
To edit from a long-lived micro plan pane, reload before changing anything: press Ctrl-e,
run reload, then press Ctrl-e again and run set readonly false. This keeps edits based
on the current file instead of a stale monitoring buffer.
Plan paths may be relative to the workspace/current working directory or absolute. Absolute paths are accepted as-is, so standalone/non-Hive use can attach personal plan files outside the repository root.
Sidebar symbols may occupy one or two terminal cells. state selects one mutually
exclusive provider; slots is an ordered list and may contain any number of columns.
Additional field providers can be declared in config. Python entry points in
hive_ide.sidebar_providers may contribute the same normalized field definitions; pane
processes read only the resulting JSON snapshot and never import plugin code.
Create managed stable and editable development environments, then switch one session without affecting the others:
hive-ide environment-setup --dev-checkout=.
hive-ide source-set --session-id=<ID> --source=dev
hive-ide source-set --session-id=<ID> --source=stable
Use hive-ide sleep [--session-id=<ID>] to stop the live agent process while keeping
the session in the active list. Sleeping sessions show the sleep status glyph, keep
their sidebar/plan panes, and wake deliberately through hive-ide chat --session-id=<ID>.
The session options menu also exposes sleep agent for Claude/Codex-style sessions.
Archive is stronger: hive-ide archive --session-id=<ID> closes the live tmux window
before moving the session out of the active list. The JSON result includes
archive.memory_released; if the window exists but cannot be closed, archive refuses
instead of hiding an agent that is still consuming memory.
Monitor local agent memory:
hive-ide monitor
hive-ide top --workspace
monitor groups live Hive IDE agent/sidebar processes by session and reports
unmatched agent processes separately. It uses /proc on Linux and ps on
macOS. --workspace limits the report to the current workspace.
Preview machine-global Claude and Codex status hooks before applying them:
hive-ide hook-setup
hive-ide hook-setup --apply
Pane leases
Any program can temporarily borrow the PLAN pane without calling tmux:
hive-ide pane-lease --session-id ID --role plan --title Monitor -- python -m my_monitor
hive-ide pane-status --session-id ID
hive-ide pane-release --lease LEASE_ID --token TOKEN
Acquisition returns the lease ID and release token. The package supervisor runs
the command on the pane's tty, then restores the currently linked plan on
exit or release, including crashes and startup failures. With no plan it shows
No plan linked. Restoration failures print a reason and open a shell. If the
supervisor is killed, repair (or the next acquire/release) restores the pane.
Live leases protect the pane from plan changes, repair, and rebuild unless
explicitly revoked with --force; the caller-pane guard still applies.
The sidebar plan slot shows ▶ while borrowed. <prefix> m focuses the lease;
<prefix> g focuses it without sending editor commands. Clients should probe
capabilities through the session's pinned interpreter and check for
pane-lease in features. All panes expose HIVE_IDE_PANE_ROLE; borrowed
commands also receive HIVE_IDE_PANE_LEASE.
See the lease contract for errors, recovery limits, and state records, and keys for shortcuts.
Development
See CONTRIBUTING.md.
License
MIT. See LICENSE.
About
hive-ide is part of Meli Hive. It is being built as a standalone
MIT-licensed project with no dependency on the rest of the platform.
1 maintainer
Metadata
1 maintainer
Release files for hive-ide 1.0.88
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| hive_ide-1.0.88.tar.gz | 247.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hive_ide-1.0.88-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 411.9 kB
Release files / hive_ide-1.0.88.tar.gz
| Download URL | hive_ide-1.0.88.tar.gz |
|---|---|
| Size | 247.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2bd23ffe89ef2b7521b4b02a9e01c857b65c460e3af2daa859475d6ddd3f52c4
|
|
BLAKE2b-256 checksum How to use checksums |
36553dc5138bc0a9520dd9becbbf09a64698cb53f4e0da39cfee864d0319776f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logRelease files / hive_ide-1.0.88-py3-none-any.whl
| Download URL | hive_ide-1.0.88-py3-none-any.whl |
|---|---|
| Size | 164.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5fb37f345b6b54bb4ae8d2b1e7c174235b5661fbcd74f692c2e87d1d039d2fab
|
|
BLAKE2b-256 checksum How to use checksums |
2a2c822489e43b688f139fbc3eabfa9859bbee761368bc9a994418545d876b44
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency log
