{
"markdown": "\n\n# ⚡ Entity\n\n**An AI-native workspace where humans can see, steer, and review agent work.**\n\nEntity gives agents a real operating surface: tasks, files, documents, chat, activity, services, plugins, and review state in one shared UI.\n\n\n\n
\n\n---\n\n## TL;DR\n\n```bash\ngit clone https://github.com/h-mascot/entity.git\ncd entity\nnpm install\nnpm run setup # creates local config and pins the ClickClack sidecar\nnpm run build\nnpm run doctor # verifies config, paths, build outputs, and private-default scan\nnpm run dev # starts Entity + ClickClack at http://localhost:3000\n```\n\nOpen `http://localhost:3000`. No hardcoded paths, no Enterprise assumptions - just a local workspace you control.\n\n---\n\n## The Vision\n\nWe're building toward a future where humans and AI agents share the same workspace for all knowledge work — writing, planning, researching, coding, managing projects, making decisions.\n\nNot AI as a tool you prompt. AI as a colleague that sits next to you.\n\n**Entity** is that workspace. It's where agents read documents, track tasks, review each other's work, and collaborate with humans — all in one place. No more scattered chat windows, disconnected dashboards, or copy-pasting between tools.\n\nOne workspace. Everything visible. Humans and AI, working together.\n\n### Why this matters\n\nToday, AI agents live in chat threads. They respond, then disappear. There's no persistent environment where they can:\n\n- Edit documents alongside you\n- Track and manage their own tasks\n- See what other agents are working on\n- Leave comments, suggestions, and reviews on shared files\n- Build institutional memory across sessions\n\nEntity changes that. It gives agents — and the humans who work with them — a **shared home**.\n\n### Starting small, thinking big\n\n[Henry](https://henrymascot.com) and the [Enterprise Crew](https://github.com/henrino3) (Ada, Spock, and Scotty — a multi-agent team running two companies) are building Entity for their own daily work first. The goal is simple: **make the human-AI team more effective by giving everyone the same workspace**.\n\nIf it works for us, it'll work for others.\n\n---\n\n## Why Entity Exists\n\nMost AI agent work disappears into chat transcripts, terminal scrollback, or one-off task runners. Humans then have to reconstruct what happened: which files changed, which task moved, what evidence exists, who reviewed it, and what is still blocked.\n\nEntity is the workspace layer for agent-native work:\n\n- agents get a visible desk instead of a hidden process\n- humans can inspect active work, handoffs, evidence, and review state\n- files, tasks, chat, documents, and operational state stay connected\n- local-first projects can grow into multi-agent operations without losing receipts\n\nThe short version: **agents should not just talk. They should have a desk.**\n\n---\n\n## Highlights\n\n| Surface | What it gives you |\n|---|---|\n| **Mission Control** | Kanban-style execution lanes, task detail panels, assignment, priority, stale-work signals, notes, links, comments, activity, and review routing. |\n| **Agent Fleet** | Live-ish agent registry/status, model/runtime metadata, current focus, handoff context, activity, and health signals. |\n| **Files / DocHub** | Multi-source file browsing, markdown preview, editing, search, share/deep links, file history, and source management. |\n| **Agent-native editor** | Collaboration foundations for comments, suggestions, reviews, presence, authorship, and shared document state. |\n| **Chat surfaces** | Thread/channel chat UI with routing and model-selection plumbing. |\n| **Services + plugins** | Admin surfaces for Entity services, plugin registry, Entity Linker, Swarm/dispatch providers, and operational integrations. |\n| **Desktop + mobile shells** | Electron desktop wrapper and Expo mobile WebView shell for running the same workspace outside a browser tab. |\n\n---\n\n## Screenshots\n\n| Mission Control | Agent Fleet |\n| :---: | :---: |\n|  |  |\n\n| Files and Documents | Workspace Shell |\n| :---: | :---: |\n|  |  |\n\n---\n\n## Quick Start Paths\n\n| Path | Best for | Status |\n|---|---|---|\n| **Run from source** | Developers and operators evaluating Entity locally | Works today |\n| **Frontend + API dev loop** | UI work with Vite hot reload | Works today |\n| **Desktop shell** | Electron wrapper around the Entity workspace | Works today, developer-oriented |\n| **Mobile shell** | Expo/WebView experiments | Present, not the polished public install path yet |\n| **Hosted / one-click deploy** | Public demo and non-dev users | Roadmap |\n\n### Prerequisites\n\n- Node.js 20+\n- npm\n- macOS or Linux recommended for local development\n\n### Install\n\n```bash\ngit clone https://github.com/h-mascot/entity.git\ncd entity\nnpm install\ncp .env.example .env\n```\n\n### First-run setup\n\n```bash\nnpm run setup\n# Interactive prompts:\nnpm run setup -- --interactive\n```\n\nThis generates `entity.config.yaml` with localhost-only workspace settings, prepares local data/log directories, verifies Go/git/npm, and clones/checks out the pinned ClickClack sidecar. Use `npm run setup -- --skip-clickclack` if you only want the Entity shell.\n\n### Run the full app locally\n\n```bash\nnpm run dev\n```\n\n`npm run dev` starts or reuses the local ClickClack sidecar at `http://127.0.0.1:3091`, mounts the embedded ClickClack UI/API under Entity, and serves Entity at `http://localhost:3000`. Set `ENTITY_CHAT_CLICKCLACK_BRIDGE=1` only when you want `/api/chat/send` compatibility traffic routed through the sidecar.\n\nUseful checks:\n\n```bash\nnpm run doctor\nnpm run clickclack:smoke\n```\n\nOr build and run manually:\n\n```bash\nnpm run build\nPORT=3000 npm --prefix packages/server run dev\n```\n\nThe server serves the built frontend from `packages/app/dist` on port `3000`.\n\nOpen:\n\n```text\nhttp://localhost:3000\n```\n\n### Frontend-only development\n\nRun the API server and Vite separately:\n\n```bash\n# terminal 1\nPORT=3000 npm --prefix packages/server run dev\n\n# terminal 2\nVITE_ENTITY_API_BASE=http://localhost:3000 \\\nVITE_ENTITY_WS_URL=ws://localhost:3000 \\\nnpm --prefix packages/app run dev\n```\n\nOpen Vite at:\n\n```text\nhttp://localhost:5173\n```\n\n### Desktop shell\n\n```bash\nnpm run desktop\n```\n\nOpens Entity as a standalone Electron window. It connects to the local server at `http://127.0.0.1:3000` (override with `ENTITY_URL`) and auto-starts the server from this repo when it isn't already running.\n\nFor packaged desktop builds (dmg/nsis, run on the target OS):\n\n```bash\nnpm run electron:build\n```\n\n### Mobile app (Expo)\n\n```bash\ncd packages/mobile && npx expo start\n```\n\nScan the QR code with [Expo Go](https://expo.dev/go) on your phone. See `packages/mobile/README.md` for LAN setup and standalone EAS builds.\n\n---\n\n## Commands\n\n| Command | Purpose |\n|---|---|\n| `npm install` | Install workspace dependencies |\n| `npm run setup` | Interactive first-run setup for `entity.config.yaml` |\n| `npm run setup -- --defaults` | Non-interactive setup with safe local defaults |\n| `npm run doctor` | Verify config, local paths, build outputs, and private-default scan |\n| `npm run build` | Build frontend, DB package, and server |\n| `npm --prefix packages/app run build` | Build the Vite frontend only |\n| `npm --prefix packages/server run build` | Build the server only |\n| `npm --prefix packages/server run test` | Run the server Vitest suite |\n| `npm run test:e2e` | Run the browser E2E smoke script |\n| `npm run electron` | Start the Electron desktop shell |\n| `npm run electron:build` | Build packaged desktop app |\n| `npm run ctrl:full` | Run this repo's release/check gates |\n| `npm run scan:private-defaults` | Scan for private defaults before public/release work without rewriting the baseline |\n| `npm run scan:private-defaults -- --write-baseline` | Intentionally refresh `docs/reports/private-default-scan-baseline.md` |\n\n---\n\n## Runtime safety configuration\n\n- `ENTITY_FS_AUDIT_MAX_FILE_BYTES` may lower the filesystem index limit, but cannot raise it above the 16 MiB hard ceiling. Local and remote reads enforce the effective byte ceiling at adapter I/O, including sources that omit file-size metadata. Oversized files are removed from the searchable index without being fully buffered; the source file itself is never modified.\n- `ENTITY_BASE_URL` is the trusted canonical runtime origin used by Services discovery and links. Deployments populate it from the lane's configured HTTP host; request `Host` headers never select discovery targets or cache identities. Manual refresh bypasses freshness at most once per cache key every 15 seconds.\n\n## Configuration\n\nEntity is local-first. Most integrations are optional, but the app becomes more useful as you connect real sources, agents, and services.\n\nCommon environment variables:\n\n| Variable | Purpose |\n|---|---|\n| `ENTITY_CONFIG` | Path to `entity.config.yaml`; defaults to the repo-local file created by `npm run setup` |\n| `PORT` | Entity server port, default `3000` |\n| `ENTITY_DB_MODE` | Database mode; local development defaults to SQLite |\n| `ENTITY_TASK_DB_PATH` | SQLite DB path override; setup/dev default to `./data/entity.sqlite` |\n| `ENTITY_CLOUD_API_BASE` | Base URL for Entity's own API when a deployment needs an explicit origin |\n| `VITE_ENTITY_API_BASE` | Frontend API base URL when using the Vite dev server |\n| `VITE_ENTITY_WS_URL` | Frontend WebSocket URL when using the Vite dev server |\n| `VITE_ENTITY_WS_PORT` | WebSocket port override used by the frontend runtime config |\n| `VITE_MC_ORIGIN` | Mission Control API origin override |\n| `VITE_OPENCLAW_BASE` | OpenClaw-compatible gateway URL for agent/runtime integrations |\n| `ENTITY_FS_MULTISOURCE` | Enable multi-source file workspace behavior |\n| `ENTITY_FS_INDEXER_ENABLED` | Enable or disable file indexing |\n| `SENTRY_DSN` / `VITE_SENTRY_DSN` | Optional backend/frontend Sentry reporting |\n\nPrivate deployments may have additional `.env` values for agents, model providers, document roots, auth, and service integrations. Do not commit secrets. Prefer `entity.config.yaml` for non-secret runtime defaults so setup, dev, doctor, and server bootstrap resolve the same profile.\n\n### Production deploy profile\n\n`./deploy.sh` is fail-closed. It has no built-in production host, directory, DB, service name, or private workspace. A production deploy must provide an explicit profile through environment variables:\n\n| Variable | Required | Purpose |\n|---|---:|---|\n| `ENTITY_PROD_HOST` | yes | SSH target for the deployment host |\n| `ENTITY_PROD_HTTP_HOST` | yes | HTTP host or full URL used for post-deploy verification |\n| `ENTITY_PROD_DIR` | yes | Remote Entity install directory |\n| `ENTITY_PROD_DB` | yes | Remote SQLite DB path to verify, back up, and preserve |\n| `ENTITY_PROD_PORT` | no | Runtime/verification port when `ENTITY_PROD_HTTP_HOST` is a hostname; defaults to `3000` |\n| `ENTITY_RUNTIME_WORKSPACE` | no | Runtime workspace path passed to the server process |\n| `ENTITY_PROD_LOG_PATH` | no | Remote fallback log path when not using a service manager |\n| `ENTITY_PROD_LAUNCHD_SERVICE` | no | macOS launchd service label to restart instead of starting a fallback process |\n| `ENTITY_PROD_NODE_ENTRY` | no | Server entrypoint relative to `ENTITY_PROD_DIR` for fallback process start |\n\nKeep private deployment values in internal docs or a private profile, not in public defaults.\n\n---\n\n## Architecture\n\n```text\nentity/\n├── packages/\n│ ├── app/ # Vite + React frontend\n│ ├── server/ # Express/WebSocket API server\n│ ├── db/ # SQLite repositories and DB connection\n│ ├── mobile/ # Expo mobile shell\n│ └── desktop/ # desktop package wrapper\n├── electron/ # canonical Electron app/build config\n├── docs/ # product docs, plans, context, specs, reports\n├── e2e/ # browser smoke tests\n└── package.json # npm workspaces root\n```\n\n### Stack\n\n- **Frontend:** React 18, TypeScript, Vite 5, Tailwind CSS, CodeMirror 6, Tiptap, Zustand\n- **Backend:** Express 4, WebSocket (`ws`), TypeScript, Vitest\n- **Database:** SQLite via `better-sqlite3`\n- **AI/runtime plumbing:** Vercel AI SDK, Google Gemini adapter, OpenClaw-compatible agent/runtime integrations\n- **Desktop:** Electron 34\n- **Mobile:** Expo SDK 52 / React Native WebView\n\n### Design principles\n\n- **Agent-native:** agents are first-class workspace users, not invisible background jobs.\n- **Visible work:** task state, activity, evidence, review, and handoffs should be inspectable.\n- **Local-first:** useful on one machine with SQLite; cloud and sync can layer on later.\n- **Receipts over vibes:** screenshots, logs, task history, and review notes beat unverifiable claims.\n- **Dark-first and keyboard-friendly:** built for long-running operational work, not a marketing dashboard pretending to be ops.\n\n---\n\n## Security and Public-Readiness Notes\n\nEntity is transitioning from an internal workspace to a public project. Before deploying a fork or exposing it beyond localhost:\n\n1. Copy `.env.example` to `.env` and keep real secrets out of git.\n2. Run the private-default scan.\n3. Review configured file roots and document sources before exposing the UI on a LAN/VPN/public host.\n4. Treat the SQLite DB as local state; do not overwrite production DB files during deploys.\n5. Put authentication/reverse-proxy controls in front of remote deployments until a hardened public auth path is documented.\n\nRecommended gate:\n\n```bash\nnpm run scan:private-defaults -- --enforce\nnpm run build\nnpm --prefix packages/server run test\n```\n\nUseful public-readiness docs:\n\n- `docs/config/private-default-scan.md`\n- `docs/config/entity-config.md`\n- `docs/specs/settings-backed-portability-spec.md`\n- `docs/reports/private-default-scan-baseline.md`\n\n---\n\n## Operator Quick Refs\n\n| Goal | Start here |\n|---|---|\n| Understand the product and architecture | `docs/context/entity-context.md` |\n| Configure Entity | `docs/config/entity-config.md` |\n| Check public/private defaults | `docs/config/private-default-scan.md` |\n| Build plugins | `docs/ENTITY-PLUGIN-BUILD-GUIDE.md` |\n| Understand plugin architecture | `docs/PLUGIN-ARCHITECTURE-SPEC.md` |\n| Prepare a public/release pass | `npm run scan:private-defaults && npm run build` |\n\n---\n\n## Troubleshooting\n\n### Workspace loads but data looks empty\n\n- Confirm the API server is running on the port your frontend expects.\n- If using Vite, set `VITE_ENTITY_API_BASE=http://localhost:3000`.\n- Check browser devtools for failed `/api/*` or WebSocket requests.\n\n### WebSocket connection fails in Vite dev mode\n\nSet either a full URL or port override:\n\n```bash\nVITE_ENTITY_WS_URL=ws://localhost:3000 npm --prefix packages/app run dev\n# or\nVITE_ENTITY_WS_PORT=3000 npm --prefix packages/app run dev\n```\n\n### Build succeeds but the server serves an old UI\n\nRebuild the frontend before starting the server:\n\n```bash\nnpm --prefix packages/app run build\nPORT=3000 npm --prefix packages/server run dev\n```\n\n### Remote/LAN access fails\n\n- Bind the server to a reachable interface if your environment requires it.\n- Use the machine's LAN/VPN hostname in `VITE_ENTITY_API_BASE` and `VITE_ENTITY_WS_URL`.\n- Put auth/reverse-proxy controls in front of anything exposed beyond your own machine.\n\n---\n\n## Roadmap\n\n### Shipped / present today\n\n| Feature | Status |\n|---|---|\n| Files / DocHub | Multi-source file browser, preview, edit, search, links, history |\n| Mission Control | Kanban/task board, task detail panels, notes, comments, activity, review routing |\n| Agent Dashboard | Agent registry/status, focus, activity, model/runtime metadata |\n| Agent-native editor foundations | Comments, suggestions, presence, reviews, shared state primitives |\n| Plugin/service registry | Entity services, plugins, Linker, Swarm/dispatch admin surfaces |\n| Chat surfaces | Thread/channel UI with routing and model-selection plumbing |\n| Desktop shell | Electron wrapper |\n| Mobile shell | Expo WebView shell |\n\n### In progress / next\n\n| Feature | Status |\n|---|---|\n| Public demo/default configuration | Needed for low-friction evaluation |\n| Portable first-run setup wizard | Present; run `npm run setup` or `npm run setup -- --defaults` |\n| Browser pane / computer-use surface | Planned |\n| Third-party install hardening | In progress |\n| Hosted/public deployment guide | Planned |\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for setup, test, and PR expectations.\n\n---\n\n## License\n\nEntity is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).\n\n---\n\n\n\nBuilt by humans and AI, for humans and AI.\n\n**[Entity on GitHub](https://github.com/h-mascot/entity)**\n\n
\n",
"bytes": 16801,
"sha": "42db783514257f8390b877cd2abbeb12291d518185b0f2bc2b475f7e041c565b",
"repo_slug": "h-mascot/entity",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/okf_h_mascot_entity_openwiki_index_md_7265bf6b/readme"
}