Gini Agent

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.

Docs

• Whitepaper: the gaps this project is closing and the bar it's measured against
• Architecture Overview: gateway/client map
• Gateway And Control Plane: runtime process, BFF, auth, instances, ports, disk layout
• Conversation And Runs: chat, runs, tasks, plan steps, traces, and audit handoff
• Memory: retain, recall, embeddings, reranking, review, and storage
• Skill Learning From Skills: how Gini improves its own skills from task outcomes (two-tier reward, attribution, the daily review, the human gate)
• Runtime Capabilities: current CLI/API capability map and verification commands
• Model Providers: per-provider setup guides (credentials, prerequisites, CLI/web config) for OpenAI, Anthropic, Bedrock, Azure, OpenRouter, DeepSeek, Codex, and Local
• Operations: install, start, stop, smoke, diagnostics, and cleanup
• Remote Access: tunnel modes and confirmation, plus a self-contained guide per tunnel provider — Gini Relay, Tailscale, ngrok, Cloudflare — the same pages the app opens inline
• Releases: versioning, CHANGELOG conventions, and the release process
• Migrating from openclaw: import an existing openclaw install into gini
• Implementation Notes: source layout and module boundary rules
• Roadmap: shipped surfaces and what's planned, with design intent

Architecture decisions

• Architecture Decision Records: index of all ADRs and how to add new ones

Architecture In One Sentence

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

What's in the box

• Authenticated localhost gateway and a Next.js + Tailwind + shadcn/ui control plane
• Persistent chat, runs, tasks, approvals, traces, audit events, jobs, memories, and skills
• Approval-gated file, terminal, and code tools
• Provider support: Codex OAuth; OpenAI / Azure OpenAI / DeepSeek / OpenRouter API keys; the first-party Anthropic Claude API; Amazon Bedrock (model-agnostic Converse, AWS SigV4 — Claude, Nova, Llama, Mistral, DeepSeek); and any OpenAI-compatible local server
• Local embeddings, reranking, and voice-message speech-to-text by default
• Parallel instances with isolated state, ports, and logs

See the Whitepaper and Architecture Overview for the design.

Quick Start

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. The form offers the full provider catalog — OpenAI, Codex, Anthropic, Amazon Bedrock, Azure OpenAI, OpenRouter, DeepSeek, and Local — and prompts for whatever the one you pick needs (an API key, the AWS access key pair for Bedrock, the resource endpoint for Azure, or your existing codex login auth). Save it 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:

• web: http://127.0.0.1:7777
• runtime: http://127.0.0.1:7778

Update

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

From source

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.

CLI

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

Providers

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
gini provider set anthropic claude-opus-4-8 # first-party Claude API, uses $ANTHROPIC_API_KEY
# Amazon Bedrock: model-agnostic Converse, SigV4-signed with AWS keys you enter via the web form or `gini setup`
gini provider set bedrock us.amazon.nova-pro-v1:0 --aws-region us-east-1  # sets model + region; enter keys separately
# Azure OpenAI: a first-class provider targeting a deployment on your resource
gini provider set azure gpt-4o \
  --base-url https://<resource>.openai.azure.com \
  --deployment <deployment> --api-version 2024-10-21 --auth-scheme api-key  # uses $AZURE_OPENAI_API_KEY

For step-by-step setup of each provider — getting credentials, installing any prerequisite tooling (Ollama, …), and configuring it in the CLI or web — see the per-provider guides: OpenAI, Anthropic, Amazon Bedrock, Azure OpenAI, OpenRouter, DeepSeek, Codex, and Local. The providers index lists them all with their auth model at a glance.

The local provider works with any OpenAI-compatible server (oMLX, vLLM, LM Studio, llama.cpp). The azure provider targets an Azure OpenAI resource: set --base-url to https://<resource>.openai.azure.com and pick a deployment; --api-version defaults to a GA value and --auth-scheme defaults to api-key (a resource key), with bearer available for an Entra token. 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 and Azure OpenAI As A First-Class Provider for the Azure routing contract. When a credential fails mid-chat, see Codex re-authentication and Provider Re-Authentication Guidance.

gini setup's interactive picker covers every provider — OpenAI, Codex, Anthropic, Amazon Bedrock, Azure OpenAI, OpenRouter, DeepSeek, and Local — prompting for whatever each one needs (an API key, the AWS access key + secret for Bedrock, the resource endpoint and deployment for Azure, the base URL for Local). gini provider set … (above) and the web Settings → Add provider form remain available for scripted or non-interactive configuration.

Parallel Instances

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.

Messaging channels

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](docs/adr/telegram-bridg