hive-ide 1.0.0__tar.gz

hive_ide-1.0.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to `hive-ide` will be documented in this file.
+
+## Unreleased
+
+## [1.0.0] - 2026-07-28
+
+### Added
+
+- Standalone, directory-scoped session storage keyed by immutable session IDs.
+- A tmux frame with responsive sidebar, agent pane, plan pane, and configurable keys.
+- Claude Code, Codex, Antigravity, and terminal drivers behind plugin entry points.
+- Configurable sidebar state and icon-slot providers.
+- Stable and editable development environments with per-session source switching.
+- Agent status and compaction lifecycle hooks.

hive_ide-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# Contributing
+
+`hive-ide` requires Python 3.10+, `tmux`, and a Unix-like system.
+
+```sh
+python3 -m venv .venv-dev
+.venv-dev/bin/python -m pip install -e ".[test,release]"
+.venv-dev/bin/python -m pytest
+.venv-dev/bin/python -m build
+.venv-dev/bin/python -m twine check dist/*
+```
+
+Keep the standalone package host-neutral. Host-specific workspace, plan, and command
+behavior belongs behind adapters or plugin entry points.

hive_ide-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dynamite Ventures
+
+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.

hive_ide-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include CHANGELOG.md
+include CONTRIBUTING.md

hive_ide-1.0.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: hive-ide
+Version: 1.0.0
+Summary: An agent-aware tmux workspace for coding agents
+Author: Meli Hive
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/melihive/hive-ide
+Project-URL: Changelog, https://github.com/melihive/hive-ide/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/melihive/hive-ide/issues
+Project-URL: Source, https://github.com/melihive/hive-ide
+Keywords: ai-agents,claude-code,codex,terminal,tmux
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=6; extra == "release"
+Dynamic: license-file
+
+# 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
+
+```sh
+python3 -m pip install hive-ide
+hive-ide create --name=MAIN --driver=term
+hive-ide open
+```
+
+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.
+
+An existing Git worktree is just a session working directory. The IDE attaches to it but
+never creates, merges, or removes it:
+
+```sh
+hive-ide create --name=FEATURE --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:
+
+```sh
+hive-ide current-plan
+hive-ide current-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.
+
+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`:
+
+```json
+{
+  "editor": "nvim --clean",
+  "keys": {
+    "prefix": "C-a",
+    "bindings": {"next": "n", "previous": "p", "error": null}
+  },
+  "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"}}
+    }
+  }
+}
+```
+
+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:
+
+```sh
+hive-ide environment-setup --dev-checkout=.
+hive-ide source-set --session-id=<ID> --source=dev
+hive-ide source-set --session-id=<ID> --source=stable
+```
+
+Preview machine-global Claude and Codex status hooks before applying them:
+
+```sh
+hive-ide hook-setup
+hive-ide hook-setup --apply
+```
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## About
+
+`hive-ide` is part of [Meli Hive](https://melihive.com). It is being built as a standalone
+MIT-licensed project with no dependency on the rest of the platform.

hive_ide-1.0.0/README.md

@@ -0,0 +1,107 @@
+# 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
+
+```sh
+python3 -m pip install hive-ide
+hive-ide create --name=MAIN --driver=term
+hive-ide open
+```
+
+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.
+
+An existing Git worktree is just a session working directory. The IDE attaches to it but
+never creates, merges, or removes it:
+
+```sh
+hive-ide create --name=FEATURE --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:
+
+```sh
+hive-ide current-plan
+hive-ide current-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.
+
+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`:
+
+```json
+{
+  "editor": "nvim --clean",
+  "keys": {
+    "prefix": "C-a",
+    "bindings": {"next": "n", "previous": "p", "error": null}
+  },
+  "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"}}
+    }
+  }
+}
+```
+
+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:
+
+```sh
+hive-ide environment-setup --dev-checkout=.
+hive-ide source-set --session-id=<ID> --source=dev
+hive-ide source-set --session-id=<ID> --source=stable
+```
+
+Preview machine-global Claude and Codex status hooks before applying them:
+
+```sh
+hive-ide hook-setup
+hive-ide hook-setup --apply
+```
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## About
+
+`hive-ide` is part of [Meli Hive](https://melihive.com). It is being built as a standalone
+MIT-licensed project with no dependency on the rest of the platform.

hive_ide-1.0.0/hive_ide/__init__.py

@@ -0,0 +1,13 @@
+"""Public package surface for hive-ide."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+PROTOCOL_VERSION = 1
+SCHEMA_VERSION = 1
+
+try:
+    __version__ = version("hive-ide")
+except PackageNotFoundError:
+    __version__ = "0.1.0.dev0"
+
+__all__ = ["PROTOCOL_VERSION", "SCHEMA_VERSION", "__version__"]

hive_ide-1.0.0/hive_ide/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

hive_ide-1.0.0/hive_ide/activity.py

@@ -0,0 +1,65 @@
+"""Fail-open activity markers for processes running inside a session."""
+
+from __future__ import annotations
+
+import os
+
+from .store import StateStore, utc_now
+
+
+class IdeActivity:
+    KIND_TASK = "task"
+    STATE_RUNNING = "running"
+    STATE_BLOCKED = "blocked"
+
+    @staticmethod
+    def _target() -> tuple[StateStore, str] | None:
+        state_home = os.environ.get("HIVE_IDE_STATE_HOME")
+        workspace = os.environ.get("HIVE_IDE_WORKSPACE_KEY")
+        session_id = os.environ.get("HIVE_IDE_SESSION_ID")
+        if not state_home or not workspace or not session_id:
+            return None
+        return StateStore(state_home, workspace), session_id
+
+    @staticmethod
+    def mark(kind: str, *, label: str = "", state: str = "running") -> bool:
+        try:
+            target = IdeActivity._target()
+            if target is None:
+                return False
+            store, session_id = target
+            with store.mutation_lock():
+                if store.find_session(session_id) is None:
+                    return False
+                store.write(
+                    "activity",
+                    session_id,
+                    {
+                        "schema_version": 1,
+                        "session_id": session_id,
+                        "workspace_key": store.workspace_key,
+                        "kind": kind,
+                        "state": state,
+                        "label": label,
+                        "observed_at": utc_now(),
+                    },
+                )
+            return True
+        except Exception:
+            return False
+
+    @staticmethod
+    def blocked(kind: str, *, label: str = "") -> bool:
+        return IdeActivity.mark(kind, label=label, state=IdeActivity.STATE_BLOCKED)
+
+    @staticmethod
+    def clear() -> bool:
+        try:
+            target = IdeActivity._target()
+            if target is None:
+                return False
+            store, session_id = target
+            with store.mutation_lock():
+                return store.delete("activity", session_id)
+        except Exception:
+            return False

hive_ide-1.0.0/hive_ide/adapters.py

@@ -0,0 +1,57 @@
+"""Optional host integration contracts.
+
+The standalone core uses these neutral defaults. A host may provide richer behavior
+to foreground commands; spawned panes receive only the resulting JSON state.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class Workspace:
+    key: str
+    working_dir: str
+    metadata: dict[str, object]
+
+
+class WorkspaceAdapter(Protocol):
+    def resolve(self, directory: Path) -> Workspace: ...
+
+
+class PlanAdapter(Protocol):
+    def resolve(self, reference: str | None, workspace: Workspace) -> dict[str, object]: ...
+
+    def active_task(self, plan: dict[str, object]) -> str | None: ...
+
+
+class CommandSurface(Protocol):
+    def before_create(self, workspace: Workspace, name: str) -> None: ...
+
+    def after_archive(self, session: dict[str, object]) -> None: ...
+
+
+class DefaultWorkspaceAdapter:
+    def resolve(self, directory: Path) -> Workspace:
+        resolved = str(directory.expanduser().resolve())
+        return Workspace(key=resolved, working_dir=resolved, metadata={})
+
+
+class DefaultPlanAdapter:
+    def resolve(self, reference: str | None, workspace: Workspace) -> dict[str, object]:
+        return {"path": reference, "active_task": None}
+
+    def active_task(self, plan: dict[str, object]) -> str | None:
+        value = plan.get("active_task")
+        return value if isinstance(value, str) else None
+
+
+class DefaultCommandSurface:
+    def before_create(self, workspace: Workspace, name: str) -> None:
+        return None
+
+    def after_archive(self, session: dict[str, object]) -> None:
+        return None

hive_ide-1.0.0/hive_ide/agentmodal.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""Guided 'change agent' modal — arrow-select, ESC-cancelable — in a tmux popup.
+
+The visual twin of `ide_newmodal`'s driver step, but for an existing session: pick the
+occupant the middle pane should run with ↑/↓ (or j/k, or 1-4), Enter to switch, and
+ESC to cancel. The currently-running occupant is
+marked and pre-selected, so Enter-on-it is a deliberate no-op rather than a surprise
+switch.
+
+It deliberately reuses `IdeNewModal`'s primitives — the SSH-timing-safe `_getkey`, the
+colour constants, and the `TYPES` list — so the two modals look identical and the one
+piece of subtle input logic (the arrow-vs-Escape peek) lives in exactly one place.
+
+Stdlib only (like `ide_newmodal`); raw cbreak input, so it must not boot the foreground
+runtime. The final action invokes the public package CLI.
+
+usage: python3 -I ide_agentmodal.py <skill_dir> <repo> <window>
+"""
+from __future__ import annotations
+
+import subprocess
+import argparse
+import sys
+from pathlib import Path
+
+from .newmodal import IdeNewModal
+from .state_compat import StateIO
+
+try:                       # POSIX only (tmux is Unix); keep importable elsewhere
+    import termios
+    import tty
+except ImportError:
+    termios = None
+    tty = None
+
+
+class IdeAgentModal:
+    """One popup: arrow-select the session's occupant → switch. ESC cancels."""
+
+    DEFAULT_AGENT = "claude"   # mirrors _IdeCore.DEFAULT_AGENT; the modal must not import it
+
+    # ---- switch (testable, no tty) ----
+
+    @staticmethod
+    def _switch(skill_dir: Path, session_id: str, kind: str) -> bool:
+        """Shell the switch through the launcher — the same path `pick_agent` uses, so the
+        pane respawn/resume logic stays in one place (`switch_agent`)."""
+        ok, _ = IdeNewModal._cli(
+            skill_dir,
+            [
+                "switch-driver",
+                f"--session-id={session_id}",
+                f"--driver={kind}",
+                *(
+                    [f"--tmux-socket={IdeNewModal._tmux_socket}"]
+                    if IdeNewModal._tmux_socket
+                    else []
+                ),
+            ],
+        )
+        return ok
+
+    @staticmethod
+    def _context(skill_dir: Path, argv: list[str]) -> tuple[str, str, str] | None:
+        """`(repo, session_id, display_name)` for this popup, else None.
+
+        Resolution order is deliberate — IDENTITY first, display name only as a fallback:
+
+        1. Public session-id and workspace-key options stamped by the frame at build time.
+           Immutable: `ide rename`, tmux `automatic-rename`, and a hand rename all leave
+           them untouched, so this keeps working when the window is called something else.
+        2. `#{session_name}` / `#{window_name}` — for a frame built before the tags existed
+           (a server that has not been reopened since). Correct today, but goes stale on the
+           first rename, which is exactly why it is second.
+        """
+        M = IdeNewModal
+        sid = M._ask_tmux("#{@hive_ide_session_id}")
+        repo = M._ask_tmux("#{@hive_ide_workspace_key}")
+        if sid and repo:
+            hit = StateIO.find_by_id(skill_dir, repo, sid)
+            if hit:
+                return hit[0], hit[2]["id"], hit[1]
+            # A stamped id that resolves to nothing is a REAL error (deleted record, wrong
+            # checkout's registry) — not a reason to quietly fall back to a name that might
+            # accidentally match a different session.
+            return None
+        repo = M._resolve(argv[2] if len(argv) > 2 else None, "#{session_name}")
+        window = M._resolve(argv[3] if len(argv) > 3 else None, "#{window_name}")
+        if not repo or not window:
+            return None
+        hit = StateIO.find_by_identity(skill_dir, repo, window)
+        return (hit[0], hit[2]["id"], hit[1]) if hit else None
+
+    @staticmethod
+    def _active(skill_dir: Path, repo: str, session_id: str) -> str | None:
+        """The occupant the session runs now — None if there is no such record (the modal
+        then has nothing to change and bails, rather than inventing a default)."""
+        found = StateIO.find_by_id(skill_dir, repo, session_id)
+        if found is None:
+            return None
+        rec = found[2]
+        return (
+            (rec.get("driver") or {}).get("id")
+            or (rec.get("agents") or {}).get("active")
+            or IdeAgentModal.DEFAULT_AGENT
+        )
+
+    # ---- interactive loop (tty) ----
+
+    @staticmethod
+    def _draw(window: str, repo: str, active: str, sel: int) -> None:
+        M = IdeNewModal
+        o = [M.CLR, f"  {M.BOLD}Change agent{M.RST}\n"]
+        # Subtitle: which session, and what it runs now — the context a bare list lacks.
+        o.append(f"  {M.DIM}{window} ({repo}) — running {active}{M.RST}{M.EL}\n\n")
+        for i, (kind, label, note) in enumerate(M.TYPES):
+            picked = i == sel
+            here = kind == active
+            arrow = "▸" if picked else " "
+            # The active occupant carries a trailing "· current" so it reads even when it is
+            # NOT the highlighted row — the highlight says "will switch here", the tag says
+            # "you are here", and the two must not be confused.
+            tag = f"  {M.NAME}· current{M.RST}" if here else ""
+            if picked:
+                o.append(f"  {M.SEL} {arrow} {label}  {note} {M.RST}{tag}{M.EL}\n")
+            else:
+                o.append(f"   {arrow} {label}  {M.DIM}{note}{M.RST}{tag}{M.EL}\n")
+        o.append(f"\n  {M.DIM}↑/↓ or j/k · 1-4 or Enter → switch · Esc → cancel{M.RST}{M.EL}")
+        sys.stdout.write("".join(o))
+        sys.stdout.flush()
+
+    @staticmethod
+    def main(argv: list[str]) -> int:
+        raw = argv[1:]
+        if "--state-home" in raw:
+            parser = argparse.ArgumentParser(prog="python -m hive_ide.agentmodal")
+            parser.add_argument("--state-home", required=True)
+            parser.add_argument("--workspace-key", required=True)
+            parser.add_argument("--session-id", required=True)
+            parser.add_argument("--tmux-socket")
+            parsed = parser.parse_args(raw)
+            skill_dir = Path(parsed.state_home)
+            IdeNewModal._tmux_socket = parsed.tmux_socket or ""
+            found = StateIO.find_by_id(skill_dir, parsed.workspace_key, parsed.session_id)
+            ctx = (found[0], found[2]["id"], found[1]) if found else None
+        else:
+            if len(argv) < 2:
+                sys.stderr.write("usage: ide_agentmodal.py <state_home> [workspace] [window]\n")
+                return 2
+            skill_dir = Path(argv[1])
+            ctx = IdeAgentModal._context(skill_dir, argv)
+        # `repo`/`window` are OPTIONAL and self-resolving. They used to be passed as tmux
+        # formats from the key binding — but `display-popup` does not expand formats in its
+        # command, so the modal received the literal `#{session_name}` / `#{window_name}`,
+        # found no record, and closed instantly. That was the "flashes and closes" bug.
+        if ctx is None:
+            return IdeNewModal._bail(
+                "Could not determine which ide session this window is.",
+                "no @hive_ide_session_id on the window and no resolvable name — "
+                "run `hive-ide open` to rebuild the frame, or `hive-ide rebuild`.")
+        repo, session_id, window = ctx
+        IdeNewModal._workspace_key = repo
+        if not (termios and tty and sys.stdin.isatty()):
+            return 0                          # interactive-only; no tty → nothing to do
+        active = IdeAgentModal._active(skill_dir, repo, session_id)
+        if active is None:
+            return IdeNewModal._bail(
+                f"No ide session record for id '{session_id}'.",
+                f"looked in the protocol session registry for workspace {repo}")
+        types = IdeNewModal.TYPES
+        # Pre-select the active occupant, so opening the modal and pressing Enter keeps
+        # things as they are — the safe default for a picker over an existing session.
+        sel = next((i for i, (k, *_ ) in enumerate(types) if k == active), 0)
+        fd = sys.stdin.fileno()
+        saved = termios.tcgetattr(fd)
+        tty.setcbreak(fd)
+        sys.stdout.write("\x1b[?25l")         # hide the real cursor
+        sys.stdout.flush()
+        result = None
+        try:
+            while True:
+                IdeAgentModal._draw(window, repo, active, sel)
+                k = IdeNewModal._getkey(fd)
+                if k == "esc":
+                    return 0
+                if k in ("up", "k"):
+                    sel = (sel - 1) % len(types)
+                elif k in ("down", "j"):
+                    sel = (sel + 1) % len(types)
+                elif k.isdigit() and 1 <= int(k) <= len(types):
+                    result = types[int(k) - 1][0]
+                    break
+                elif k == "enter":
+                    result = types[sel][0]
+                    break
+        finally:
+            sys.stdout.write("\x1b[?25h")     # restore the cursor
+            termios.tcsetattr(fd, termios.TCSADRAIN, saved)
+            sys.stdout.write(IdeNewModal.CLR)
+            sys.stdout.flush()
+        if result is None or result == active:
+            return 0                          # cancelled, or picked what's already running
+        return 0 if IdeAgentModal._switch(skill_dir, session_id, result) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(IdeAgentModal.main(sys.argv))