wusterbuilds/habitat-cli

HT captures Codex and Claude Code sessions into a private local SQLite ledger you can inspect and search. Connect Habitat Cloud only when you want shared team history and hosted intelligence.

A two-minute tour of team activity, semantic summaries, usage analytics, and shared MCP tools:

• Local-first: capture, inspect, and search without an account or network.
• Read-only providers: HT never modifies Codex or Claude Code transcripts.
• Durable delivery: optional uploads use deterministic batches, cursors, retries, and per-workspace checkpoints.
• Auditable: source, fixtures, ingestion contract, installer, and release workflows are public under MIT.

HT is under active development. Expect CLI and protocol changes before 1.0, and review the privacy model before capturing sensitive projects or enabling upload.

Install the latest checksum-verified macOS or Linux release:

curl -fsSL https://app.use-habitat.com/install.sh | sh
ht install
ht sync
ht sessions list

Search or inspect captured sessions entirely on your machine:

ht sessions search "migration"
ht sessions show SESSION_ID
ht status

The installer is a convenience wrapper around public GitHub release assets. It verifies the selected binary against the release's SHA256SUMS before activation. You can review install.sh first or download an asset directly from GitHub Releases.

Run the guided setup when you want to share selected project sessions with a Habitat workspace:

ht setup

Setup logs in, lets you choose projects and a 30-day, 90-day, or all-time backfill, installs provider hooks, and schedules background capture. It never launches Codex or Claude Code and explains the Codex hook trust step rather than bypassing it.

One project routes to one workspace; delivery, retry state, and credentials stay isolated per workspace. Setup is idempotent and safe to rerun after an interruption.

For a self-hosted Habitat-compatible endpoint:

ht setup \
  --api-url http://127.0.0.1:4319 \
  --app-url http://localhost:3000

flowchart LR
  A["Codex and Claude Code logs"] -->|"read only"| B["HT normalizer + redaction"]
  B --> C["Local SQLite ledger"]
  C --> D["Local list, show, search"]
  C -->|"optional versioned batches"| E["Habitat-compatible API"]
  E --> F["Habitat Cloud team experience"]

A provider stop hook durably records the exact transcript path before waking the daemon. The first delivery is a baseline; later deliveries contain only ordered events after the acknowledged byte cursor. Immutable batch IDs make retries idempotent, while quarantine state prevents a malformed payload from blocking later work.

The public wire format, JSON Schema, compatibility policy, and synthetic fixtures live in protocol.

HT's local workflow does not depend on the private cloud codebase. Read the boundary document for contribution guidance.

Windows is not currently supported. See ROADMAP.md for how platform support is prioritized.

ht preflight                # read-only environment inspection
ht install                  # install hooks and local background service
ht setup                    # configure local capture plus Habitat Cloud
ht configure                # change project and workspace routing
ht sync                     # explicitly reconcile provider history
ht backfill                 # inspect or schedule historical capture
ht sessions list            # list local sessions
ht sessions show ID         # inspect one local session
ht sessions search QUERY    # search local content
ht status                   # concise capture and delivery health
ht doctor                   # detailed diagnostics and repair guidance
ht update                   # checksum-verified upgrade
ht logout                   # remove a workspace login
ht uninstall                # remove hooks, launcher, and service

Uninstall preserves local SQLite data and credentials so an interrupted or accidental uninstall is recoverable. Paths and environment overrides are shown with ht help and in the privacy model.

Permissioned tools and managed installers can use the same flow without terminal prompts:

printf '%s' "$HABITAT_API_KEY" | ht setup \
  --api-key-stdin \
  --project /path/to/project \
  --backfill 30d \
  --non-interactive \
  --json

An assistant should ask before changing hooks, installing a service, opening a browser, or uploading content. ht preflight --json is the read-only starting point. A real Codex hook must still be reviewed and trusted by the user.

Prerequisite: Bun 1.3+. A separate Node.js installation is not required.

git clone https://github.com/wusterbuilds/habitat-cli.git
cd ht
bun install --frozen-lockfile
bun run check
bun run build
./dist/ht --help

The release workflow builds standalone Arm and x64 binaries on native macOS and Linux runners, produces checksums and an SBOM, and publishes GitHub build provenance attestations.

• Start with CONTRIBUTING.md.
• Use the issue chooser for bugs, provider changes, and feature proposals.
• Follow SECURITY.md for private vulnerability reporting.
• Read SUPPORT.md, GOVERNANCE.md, and ROADMAP.md for project expectations.
• Review CHANGELOG.md before upgrading across minor releases.
• Maintainers should complete the launch checklist before an announcement or release.

MIT. See LICENSE. “Habitat”, “HT”, and associated logos are subject to the trademark policy.