gratico

gratico

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 for the full architecture.

---

$3

- 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.

---

$3

``bash
npx gratico
`

The command will:

1. Build and start the bundled Node server on a random available port.
2. Export WIKI_SOURCE_DIRECTORY=.
3. Print the launch URL, e.g. http://localhost:53421.

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.

---

$3

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:6350
- Web UI on http://localhost:6300

3. Quality checks:
`bash
npm test
npm run typecheck
`

---

$3

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.

---

$3

- 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.