{"id":43442105,"url":"https://github.com/cipher982/longhouse","last_synced_at":"2026-04-19T00:09:58.551Z","repository":{"id":335965345,"uuid":"942175362","full_name":"cipher982/longhouse","owner":"cipher982","description":"centralized location for managing ai agents","archived":false,"fork":false,"pushed_at":"2026-04-03T01:03:47.000Z","size":228380,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-03T09:49:21.090Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://longhouse.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cipher982.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-03-03T17:37:04.000Z","updated_at":"2026-04-03T01:03:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cipher982/longhouse","commit_stats":null,"previous_names":["cipher982/longhouse"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/cipher982/longhouse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipher982%2Flonghouse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipher982%2Flonghouse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipher982%2Flonghouse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipher982%2Flonghouse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cipher982","download_url":"https://codeload.github.com/cipher982/longhouse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipher982%2Flonghouse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31575755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-02T22:32:18.882Z","updated_at":"2026-04-19T00:09:58.518Z","avatar_url":"https://github.com/cipher982.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Longhouse\n\nLonghouse puts Claude Code, Codex CLI, and Gemini CLI sessions into one searchable timeline and keeps a control channel open when they start through Longhouse.\n\nImport sessions you already have so Longhouse is useful immediately, then start new work through Longhouse when you want to inspect, message, and keep working from the web UI, CLI, or HTTP.\n\nA session stays the same object either way. Longhouse in the launch path changes what you can do with that session later; it does not create a second class of session.\n\nWorks on your laptop. Shines on a machine that stays on.\n\nSelf-host free on the machine where work should live, or use hosted beta later when you want us to run the Longhouse runtime for you. Claude is the strongest continuation path today; Codex and Gemini are searchable and inspectable today.\n\n## Demo\n\nNo walkthrough video is published yet. The first run is simple:\n\n```bash\ncurl -fsSL https://get.longhouse.ai/install.sh | bash\n```\n\nThe installer only acquires Longhouse. It installs the `longhouse` CLI, and on macOS it also installs `Longhouse.app` in `/Applications`. On macOS, open `Longhouse.app` to finish setup. On Linux or WSL, run `longhouse onboard`.\n\nFor new work you want to keep steerable:\n\n```bash\nlonghouse claude\nlonghouse codex\n```\n\nBare `claude` and `codex` still import into the timeline, but they remain unmanaged history.\n\nIf you need repair later, start with `longhouse doctor`.\n\nThe web UI is the easiest place to look around, but the session surface is scriptable too:\n\n```bash\nlonghouse wall --json\n```\n\nIf you want a safe preview before importing real work:\n\n```bash\nlonghouse serve --demo\n```\n\n## Get Started\n\n### Try it out (laptop)\n\n```bash\ncurl -fsSL https://get.longhouse.ai/install.sh | bash\n```\n\nOn macOS, open `Longhouse.app` to finish setup. On Linux or WSL, run `longhouse onboard`, then open `http://localhost:8080`. This runs both the Machine Agent and the Runtime Host on your laptop, which is good for trying the product but stops when your laptop sleeps.\n\nOn macOS the installer puts `Longhouse.app` in `/Applications`. The direct app download lands on the same Mac product state.\n\n### macOS app download (Apple Silicon)\n\nIf you want the signed app-first path on a modern Mac, download the desktop app directly. It installs the same `Longhouse.app` product the shell bootstrap installs for macOS users:\n\n[Download Longhouse for macOS](https://longhouse.ai/download/macos)\n\n### Self-host for durability (always-on machine)\n\nFor durable session storage, run the Runtime Host on an always-on box (VPS, homelab, Mac mini) and point your laptop's Machine Agent at it:\n\n```bash\n# On your always-on box:\ncurl -fsSL https://get.longhouse.ai/install.sh | bash\nlonghouse serve --host 0.0.0.0 --port 8080 --daemon\n\n# On your dev machine(s), point the agent at the server:\nlonghouse connect --url https://longhouse.example.com --install\n```\n\n### Start control-ready sessions\n\n```bash\nlonghouse claude\nlonghouse codex\n```\n\n### Hosted beta (later)\n\nSign up at https://longhouse.ai when you want the convenience path — we run the Runtime Host for you, your dev machines only need the Machine Agent.\n\n## Features\n\n- **Find existing sessions fast**: Import and search old Claude, Codex, and Gemini work immediately\n- **Control after launch**: Start through Longhouse to keep a live control path or host reattach path available later\n- **One timeline**: Claude Code, Codex CLI, and Gemini CLI sessions in one place\n- **Search + recall**: Find messages, tool calls, file edits, and session metadata fast\n- **Agent-first coordination**: Read the wall, tail sessions, find peers, and send directed session messages by CLI or API\n- **Self-hosted or hosted**: Self-host free on an always-on machine, or use hosted beta later\n\n## Install Options\n\n### Shell installer (recommended for agents and automation)\n```bash\ncurl -fsSL https://get.longhouse.ai/install.sh | bash\n```\n\nInstalls the `longhouse` CLI, and on macOS also installs the same `/Applications/Longhouse.app` you get from the direct app download. It does not run onboarding.\n\n### macOS desktop app\n\nFor a click-first install on Apple Silicon Macs, use the direct desktop download. This is the same Mac product as the shell installer, not a separate setup path:\n\n[Download Longhouse for macOS](https://longhouse.ai/download/macos)\n\n### With `uv` (advanced / power-user path)\n```bash\nuv tool install longhouse\nlonghouse onboard\n```\n\nOn macOS, download `Longhouse.app` separately if you want the signed desktop app without using the shell bootstrap.\n\n### Repair and upgrade\n\n```bash\nlonghouse doctor              # Self-diagnosis\nlonghouse upgrade             # Upgrade the installed CLI\nlonghouse connect --install   # Repair hooks and machine agent\n```\n\nUse `serve --demo` for a safe preview before importing real work.\n\n### Local dogfood loop (repo dev)\n\nIf you are actively changing Longhouse itself and want your Mac to keep running the real product from current repo source, use:\n\n```bash\nmake dogfood-refresh\nmake dogfood-check\n```\n\n`make dogfood-refresh` is the repo-native reinstall loop for the actual local runtime. It rebuilds the Rust engine, rebuilds `Longhouse.app` from current source on macOS, and re-runs `connect --install` against your real local launchd/hooks/app state.\n\n`make dogfood-check` shows the installed runtime status and local-health summary.\n\nDo not use the DMG drag-install flow for daily dogfooding. The DMG is a release transport; the dogfood path is `make dogfood-refresh`.\n\n### 3. Advanced / contributor paths\n\nDocker is mainly for CI and contributor workflows, not the primary end-user install path.\n\n```bash\ndocker compose -f docker/docker-compose.dev.yml up\n```\n\nFrom source:\n\n```bash\ngit clone https://github.com/cipher982/longhouse\ncd longhouse \u0026\u0026 make dev\n```\n\n\u003c!-- readme-test: verifies install from source and health endpoint --\u003e\n```readme-test\n{\n  \"name\": \"longhouse-serve-health\",\n  \"mode\": \"smoke\",\n  \"workdir\": \".\",\n  \"timeout\": 240,\n  \"env\": {\n    \"AUTH_DISABLED\": \"1\",\n    \"SKIP_DEMO_SEED\": \"1\"\n  },\n  \"steps\": [\n    \"bun install --frozen-lockfile --silent\",\n    \"(cd web \u0026\u0026 bun run build)\",\n    \"uv venv .tmp-readme-serve-venv --python 3.12 -q\",\n    \". .tmp-readme-serve-venv/bin/activate\",\n    \"uv pip install -e server -q\",\n    \"DATABASE_URL=sqlite:///$(mktemp -d)/test.db longhouse serve --port 47398 \u0026\",\n    \"SERVER_PID=$!\",\n    \"for _ in $(seq 1 20); do curl -sf http://127.0.0.1:47398/api/health \u0026\u0026 break; sleep 1; done\",\n    \"curl -sf http://127.0.0.1:47398/api/health\",\n    \"kill $SERVER_PID 2\u003e/dev/null || true\"\n  ],\n  \"cleanup\": [\n    \"pkill -f 'longhouse serve.*47398' 2\u003e/dev/null || true\",\n    \"rm -rf .tmp-readme-serve-venv\"\n  ]\n}\n```\n\n## Configuration\n\n### Local defaults\n\n- Local UI: `http://localhost:8080`\n- Local database: `~/.longhouse/longhouse.db`\n- Local quickstart auth: disabled by default on localhost\n\n### Multi-machine / self-hosted on a VPS or homelab\n\nRun the server on an always-on machine (VPS, home server, Mac mini) and connect your dev machines to it.\n\n**On the server:**\n\n```bash\n# Bind to all interfaces so other machines can reach it\nlonghouse serve --host 0.0.0.0\n\n# With a domain name (stored in ~/.longhouse/config.toml for future starts)\nlonghouse serve --host 0.0.0.0 --domain longhouse.example.com\n```\n\nOn startup, Longhouse prints every URL it can be reached at:\n\n```\n  Local:    http://127.0.0.1:8080/\n  LAN:      http://192.168.1.42:8080/\n  Public:   https://longhouse.example.com/    ← only when --domain is set\n\n  To connect from another machine:\n    longhouse connect --url http://192.168.1.42:8080\n  To connect from any machine (via your domain):\n    longhouse connect --url https://longhouse.example.com\n```\n\n**On each dev machine:**\n\n```bash\n# Point this machine's agent at the server (LAN)\nlonghouse connect --url http://192.168.1.42:8080\n\n# Or with your domain\nlonghouse connect --domain longhouse.example.com\n\n# Install as a persistent background agent\nlonghouse connect --domain longhouse.example.com --install\n```\n\n**Reverse proxy (Caddy — recommended):**\n\n```\nlonghouse.example.com {\n    reverse_proxy 127.0.0.1:8080\n}\n```\n\nCaddy handles TLS automatically. No extra configuration needed on the Longhouse side.\n\n### Remote or shared access\n\nSet `LONGHOUSE_PASSWORD` (plaintext) or `LONGHOUSE_PASSWORD_HASH` (recommended) before binding beyond localhost.\n\n### Gmail Inbox Setup (Self-hosted)\n\nThe inbox Gmail flow is BYO Google config on self-hosted installs. Users will see setup errors until the instance has:\n\n- `GOOGLE_CLIENT_ID`\n- `GOOGLE_CLIENT_SECRET`\n- `GMAIL_PUBSUB_TOPIC`\n- `PUBSUB_AUDIENCE`\n\nSet `PUBSUB_SA_EMAIL` too if you want the webhook to pin Pub/Sub push auth to a specific service account.\n\nGenerate a pbkdf2 hash:\n```bash\npython - \u003c\u003c'PY'\nimport base64, hashlib, os\npassword = \"change-me\"\nsalt = os.urandom(16)\niterations = 200_000\ndk = hashlib.pbkdf2_hmac(\"sha256\", password.encode(), salt, iterations)\nprint(f\"pbkdf2_sha256${iterations}${base64.b64encode(salt).decode()}${base64.b64encode(dk).decode()}\")\nPY\n```\n\n## Commands\n\n```bash\nlonghouse serve      # Start the local runtime\nlonghouse serve --demo        # Start with sample data\nlonghouse serve --demo-fresh  # Rebuild demo data on start\nlonghouse connect             # Run the machine agent in foreground\nlonghouse connect --install   # Install hooks + background machine agent\nlonghouse ship                # One-time import pass\nlonghouse wall --json         # Read raw coordination signals\nlonghouse peers --json        # Find nearby live peer sessions\nlonghouse tail ...            # Read recent events from a session\nlonghouse message ...         # Send a durable directed session message\nlonghouse recall              # Search and find sessions\nlonghouse sessions get ...    # Get session details\nlonghouse sessions events ... # Get session events\nlonghouse auth                # Manage authentication\nlonghouse config show         # Show effective configuration\nlonghouse status              # Show local runtime status and health\nlonghouse version --check     # Check whether a CLI update is available\nlonghouse upgrade             # Upgrade the installed CLI\nlonghouse doctor              # Self-diagnosis\nlonghouse doctor --check-updates  # Include latest stable CLI check\nlonghouse onboard             # Run the default local quickstart\nlonghouse migrate             # Migrate local data to newer format\nlonghouse claude              # Start Claude Code through Longhouse\nlonghouse codex               # Start Codex CLI through Longhouse\n```\n\nInteractive CLI commands refresh update state in the background and show a\ncached upgrade hint when the installed CLI is behind the latest stable release.\n\nFor the canonical machine-facing API and copyable coordination recipes, see `docs/specs/agents-machine-surface.md`.\n\n## Troubleshooting\n\n### `longhouse: command not found` after install\n\nThe installer adds `~/.local/bin` to your shell profile, but the current terminal may not have picked it up yet.\n\n```bash\n# Option 1: reload your shell profile\nsource ~/.zshrc   # or ~/.bashrc / ~/.bash_profile\n\n# Option 2: add the path manually\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\nRun `longhouse doctor` to verify everything is working.\n\n### Claude Code not found when installing hooks\n\nClaude Code must be installed separately. `longhouse connect --install` will install the machine agent and CLI hooks for Claude Code and Codex when those CLIs are present.\n\n```bash\n# Check if claude is reachable\nwhich claude\n\n# If installed but not on PATH, add its directory:\nexport PATH=\"/path/to/claude/bin:$PATH\"\n```\n\n### Local runtime won't start (port in use)\n\n```bash\n# Find what's using the port\nlsof -i :8080\n\n# Use a different port\nlonghouse serve --port 8081\n```\n\n### Hooks not firing / sessions not shipping\n\n```bash\n# Check machine-agent status\nlonghouse connect --status\n\n# Check doctor for full diagnosis\nlonghouse doctor\n\n# Manually ship once to test\nlonghouse ship --verbose\n```\n\n`longhouse connect --install` sets up the machine agent and CLI hooks only. It does not modify your normal global Claude/Codex MCP tool menus.\n\n### Reinstalling or upgrading\n\n```bash\nlonghouse upgrade\nlonghouse doctor   # verify\n\n# or use the underlying package-manager path directly\nuv tool upgrade longhouse\nlonghouse doctor   # verify\n```\n\nFor a full disposable install -\u003e upgrade rehearsal without touching your real\nmachine state:\n\n```bash\nmake test-install-upgrade\n```\n\n## Documentation\n\n- User docs: https://longhouse.ai/docs\n- Product direction: `VISION.md`\n- Issues and bugs: https://github.com/cipher982/longhouse/issues\n\n---\n\n## For Contributors\n\nFull dev setup with hot reload:\n\n```bash\ngit clone https://github.com/cipher982/longhouse.git\ncd longhouse\nmake dev  # Starts backend + frontend\n```\n\nRun tests:\n\n```bash\nmake test          # Unit tests\nmake test-e2e      # End-to-end tests\n```\n\nNote: pre-commit hooks may auto-fix files (ruff/ruff-format, etc.). Re-stage before committing.\n\n## Architecture\n\n```\nUser → CLI (longhouse) → FastAPI backend → SQLite (~/.longhouse/longhouse.db)\n                       ↓\n                  React frontend (localhost:8080)\n```\n\n**Stack:**\n- Backend: Python 3.12+, FastAPI, SQLAlchemy, SQLite\n- Frontend: React 19, TypeScript, Vite\n- CLI: Typer, uv\n\n## Why \"Longhouse\"?\n\nTraditional longhouses were communal structures where tribes gathered and preserved history. Your Longhouse is where all your AI coding sessions gather and persist.\n\nEach session is a log in your timeline.\n\n## Status\n\n**Alpha**. Actively developed. Claude Code, Codex CLI, and Gemini CLI sessions sync today. Claude is the strongest continuation path today; Codex and Gemini are searchable and inspectable today. Hosted remains the convenience path later, not the required first step.\n\n## Author\n\nBuilt by [David Rose](https://github.com/cipher982) -- indie developer building AI agent tools.\n\n- GitHub: https://github.com/cipher982\n- Twitter/X: https://x.com/cipher982\n\n## License\n\nApache-2.0 - see LICENSE file\n\n## Links\n\n- **Documentation:** https://longhouse.ai/docs\n- **Issues:** https://github.com/cipher982/longhouse/issues\n- **PyPI:** https://pypi.org/project/longhouse/\n\n---\n\nOnboarding contract (CI). Do not edit unless the README steps change.\n\n\u003c!-- onboarding-contract:start --\u003e\n```json\n{\n  \"workdir\": \"/tmp/longhouse-onboarding\",\n  \"steps\": [\n    \"cd {{WORKDIR}}/web \u0026\u0026 bun install --silent \u0026\u0026 bun run build\",\n    \"cd {{WORKDIR}}/server \u0026\u0026 uv sync\",\n    \"cd {{WORKDIR}}/server \u0026\u0026 HOME={{WORKDIR}}/.qa-home uv run longhouse serve --host 127.0.0.1 --port 8080 --daemon\",\n    \"sleep 5\",\n    \"curl -fsS http://127.0.0.1:8080/api/health\",\n    \"cd {{WORKDIR}}/e2e \u0026\u0026 bun install --silent \u0026\u0026 PLAYWRIGHT_BASE_URL=http://127.0.0.1:8080 bunx playwright test --config playwright.onboarding.config.js --project onboarding-chromium\"\n  ],\n  \"cleanup\": [\n    \"cd {{WORKDIR}}/server \u0026\u0026 HOME={{WORKDIR}}/.qa-home uv run longhouse serve --stop || true\",\n    \"rm -rf {{WORKDIR}}/.qa-home\"\n  ],\n  \"primary_route\": \"/timeline\",\n  \"cta_buttons\": [\n    {\n      \"label\": \"Machines\",\n      \"selector\": \"button:has-text(\\\"Machines\\\")\"\n    }\n  ]\n}\n```\n\u003c!-- onboarding-contract:end --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcipher982%2Flonghouse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcipher982%2Flonghouse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcipher982%2Flonghouse/lists"}