by Lilac-Labs
The agent that remembers and learns.
# Add to your Claude Code skills
git clone https://github.com/Lilac-Labs/gini-agentLast scanned: 6/5/2026
{
"issues": [
{
"type": "npm-audit",
"message": "xlsx: Prototype Pollution in sheetJS",
"severity": "high"
}
],
"status": "WARNING",
"scannedAt": "2026-06-05T08:08:13.778Z",
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
Gini Agent is a personal agent that remembers, improves, and runs without forcing you to read a log line.
Gini is not just a chat box, CLI, messaging bot, or pile of tools. Chat is an interaction surface. The runtime is the system of record for conversations, runs, tasks, approvals, memory, skills, jobs, tools, traces, audit events, and runtime health.
Gini's runtime is the gateway: a single Bun process per instance owns state and performs work. The Next.js web app, CLI, Expo mobile app, MCP surfaces, and messaging bridges are clients of the same authenticated /api/* contract. See Architecture Overview for the design.
GATEWAY (Bun runtime, one per instance)
state, agent loop, tools, memory, jobs
^
--------------------+--------------------
| | |
Next.js BFF CLI / scripts other clients
browser UI bearer token mobile, MCP, messaging
no browser token
See the Whitepaper and Architecture Overview for the design.
curl -fsSL https://raw.githubusercontent.com/Lilac-Labs/gini-agent/main/scripts/install.sh | bash
On macOS the installer enables autostart (per-user LaunchAgents for the runtime and webapp), waits for the webapp to come up, and opens the /setup page in your browser. Pick a provider in the browser form (OpenAI API key or existing codex --login auth) and you land on the running app. The runtime stays alive across reboots and crashes until you explicitly run gini stop or gini autostart disable.
If the browser doesn't open automatically (or you want to navigate manually), run gini status to print the actual web URL. The installed default instance always lives at :7777; other instances get hash-derived ports, so check gini status rather than guessing. The installer also prints the URL right before opening the browser.
Caveat on macOS 26 (Tahoe): after a SIGKILL, launchd sometimes refuses to auto-respawn (pended nondemand spawn = inefficient). Run gini autostart kick to force a respawn when that happens; RunAtLoad still fires at login.
If you opted out of autostart (--no-autostart) or you're on Linux (autostart is currently macOS-only), run gini setup then gini start to launch the runtime by hand.
After install, the URLs are stable:
http://127.0.0.1:7777http://127.0.0.1:7778gini update
Updates the installer-managed runtime at ~/.gini/runtime and restarts it. Per-instance state under ~/.gini/instances/ and the model cache at ~/.gini/models/ are preserved.
bun install
bun run gini install
bun run gini start
From a repo clone, the instance is derived from the directory basename, so each worktree gets isolated state and ports automatically. See CONTRIBUTING.md for development setup including ./scripts/install.sh --local for testing the install flow against a local checkout.
The CLI covers chat, runs, tasks, approvals, memory, jobs, connectors, providers, snapshots, imports, and more. Discover commands with:
gini --help
Useful starting points:
gini status # runtime health and URLs
gini chat new # start a chat session
gini approvals # review pending tool approvals
(From a repo clone, prefix with bun run.)
Run gini setup for an interactive picker, or configure directly:
gini provider set codex gpt-5.5 # Codex OAuth (reads ~/.codex/auth.json)
gini provider set openai gpt-5.4-mini # uses $OPENAI_API_KEY
gini provider set openrouter <model> # uses $OPENROUTER_API_KEY
gini provider set local <model> --base-url http://127.0.0.1:8000/v1
The local provider works with any OpenAI-compatible server (oMLX, vLLM, LM Studio, llama.cpp). API keys are read from environment variables, and Codex OAuth is read from ~/.codex/auth.json (or CODEX_AUTH_JSON) — nothing is written to Gini config. Run gini --help for the full flag set, or see provider-extra-body.md for the --extra-body contract. When a credential fails mid-chat, see Codex re-authentication and Provider Re-Authentication Guidance.
Each instance has isolated state, ports, and logs:
gini --instance sandbox run
gini smoke # ephemeral instance under /tmp
Multiple agents can run smoke tests concurrently without colliding.
Gini can bridge to messaging channels such as Telegram and Discord. These bridges were added to exercise the gateway's messaging contract and are not being actively worked on. We highly recommend interacting with Gini through the native web app and iOS app. Those are the primary, actively developed surfaces. See telegram-bridge.md and discord-bridge.md for the bridge contracts.
Already running openclaw? Import your agents, chat history, memory, skills, workspace files, and messaging bridges into a gini instance. The import is two steps — plan prints a redacted summary, apply writes the state:
gini import plan openclaw # dry-run: summarize what would be imported
gini import apply openclaw # import the openclaw state into gini
apply mutates state in-process, so stop the target instance first (gini stop --instance <name>), apply, then start it again. Every applied import first archives your full openclaw state to <instance>/imports/openclaw-<timestamp>.zip, so nothing is lost. See Migrating from openclaw for the field-by-field mapping, idempotency rules, and verification steps.
~/.gini/instances/<instance>/ # config, state.json, memory.db, traces, snapshots, workspace, logs
~/.gini/models/ # shared embedding/reranker/speech-to-text model cache
Use gini uninstall to remove an instance or the whole install. See Operations for diagnostics and cleanup.
See ROADMAP.md for shipped surfaces and what's planned.
Contributions are welcome. Start with CONTRIBUTING.md for development setup, verification commands, and PR conventions. For architecture conventions and module boundaries, see AGENTS.md. Report security issues privately per SECURITY.md.