LLM-powered workspace hub that serves your local codebase over a browser UI. The hypervisor hosts the Vue frontend, ACP-powered CLI session APIs (Claude + Codex), and REST endpoints for file/database operations. See [`docs/overview.md`](./docs/overview.md
npm install graticoLLM-powered workspace hub that serves your local codebase over a browser UI. The hypervisor hosts the Vue frontend, ACP-powered CLI session APIs (Claude + Codex), and REST endpoints for file/database operations. See docs/overview.md for the full architecture.
---
- Zero-config CLI launch – run npx gratico from any directory and get a live server bound to a random port.
- Workspace aware – automatically sets WIKI_SOURCE_DIRECTORY to the directory you launched from, keeping file operations sandboxed.
- Notion-like UI – browse and edit source files, explore databases, and invoke LLM assistance in the browser.
---
``bash`
npx gratico
The command will:
1. Build and start the bundled Node server on a random available port.
2. Export WIKI_SOURCE_DIRECTORY=.http://localhost:53421
3. Print the launch URL, e.g. .
Hit the printed URL in your browser to load the workspace UI.
> Tip: Provide credentials before launching if you rely on external services:
> • ANTHROPIC_API_KEY for Claude ACP sessions OPENAI_API_KEY
> • or CODEX_API_KEY for Codex ACP WIKI_DATABASE_URL
> • (optional) for database features
Press Ctrl+C to shut down the server.
---
1. Install dependencies:
`bash`
npm install
2. Launch the dev stack (Node API worker + Vite web client):
`bash`
npm run dev
- API served from http://localhost:6350http://localhost:6300
- Web UI on
3. Quality checks:
`bash`
npm test
npm run typecheck
---
You can dry-run the published CLI without publishing to npm:
`bash`
npm run build-node
npm pack
From a temporary directory:
`bash`
mkdir /tmp/hypervisor-smoke && cd /tmp/hypervisor-smoke
npx --yes "../path/to/@graticohq-hypervisor-0.0.0.tgz"
Expected output:
``
🚀 Hypervisor ready on http://localhost:53421
📂 WIKI_SOURCE_DIRECTORY=/tmp/hypervisor-smoke
Visit the printed URL to confirm the UI loads with your test workspace.
---
- WIKI_SOURCE_DIRECTORY _(auto-set by CLI)_ – root directory for file operations.WIKI_DATABASE_URL
- – PostgreSQL connection string for database features.ANTHROPIC_API_KEY
- – unlock Claude ACP sessions.OPENAI_API_KEY
- / CODEX_API_KEY – unlock Codex ACP sessions.
Refer back to docs/overview.md` for additional design principles and roadmap items.