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.

Features

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

Quick start (published package)

npx gratico

The command will:

1. Build and start the bundled Node server on a random available port.
2. Export WIKI_SOURCE_DIRECTORY=<current working 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.

Local development

1. Install dependencies:

   npm install

2. Launch the dev stack (Node API worker + Vite web client):

   npm run dev

   • API served from http://localhost:6350
   • Web UI on http://localhost:6300

3. Quality checks:

   npm test
   npm run typecheck

Testing the npx workflow locally

You can dry-run the published CLI without publishing to npm:

npm run build-node
npm pack

From a temporary directory:

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.

Environment variables

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