Gini Agent: a local-first runtime where the agent asks for input in the chat
The agent that remembers and learns.
At a glance
- What is it?
- Gini Agent is an MIT-licensed TypeScript personal agent whose Bun gateway owns all state and whose Next.js, CLI, mobile and MCP clients share one authenticated API. The interesting part is not the agent loop but the inline controls it uses to collect secrets, sign-ins and consent.
- Who is it for?
- Adopt Gini if you want a self-hosted personal agent whose state, memory, jobs and audit trail live in one Bun process you control, and if you value the inline control primitives (secure secret fields, browser sign-in handoff, confirm-before-send) over wiring up a framework yourself.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 60 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap Gini Agent claims to close: chat as transcript versus chat as control surface
Most personal agent projects treat the conversation as the product. You type, the model answers, and when it needs something it cannot supply (an API key, a login, a decision) it writes a sentence asking you to go do that thing somewhere else. Gini Agent takes the opposite position. Its README states that "chat is an interaction surface" and that "the runtime is the system of record" for conversations, runs, tasks, approvals, memory, skills, jobs, tools, traces, audit events and runtime health. The audience is therefore narrow and specific: someone running a long-lived agent on their own hardware, doing multi-step work across tools, who is tired of being pulled out of the loop to paste credentials or babysit a browser. It is explicitly not aimed at teams who want a hosted API or a library they embed in an existing service. The project ships a control plane, a CLI, an Expo mobile client and MCP surfaces, which tells you the intended deployment is a machine you own with a UI you open.
One Bun process per instance and clients that speak the same /api contract
The architecture summary in the README is unusually blunt: "Gini's runtime is the gateway." A single Bun process per instance owns state and performs work, including the agent loop, tools, memory and jobs. Everything else is a client. The Next.js web app acts as a BFF and holds no browser token; the CLI and scripts authenticate with a bearer token; mobile, MCP and messaging bridges are described as clients of the same authenticated /api/* contract. The diagram in the README places the gateway at the top with three client families fanning out below it. Two consequences follow from that shape. First, state is not scattered across the UI and the agent process, so a run, its trace and its audit events live in one place. Second, the machine running the gateway is not where you have to be, because the same wire protocol drives the web app and the iOS app. The README notes that parallel instances get isolated state, ports and logs, which is the mechanism that makes running more than one agent on one box possible. The docs directory points to docs/architecture-overview.md and docs/gateway.md for the port and disk layout, which is where I would go before assuming two instances cannot collide on a port.
Approval-gated tools and the four inline controls the ADRs describe
The tool surface is gated: the README lists "approval-gated file, terminal, and code tools." That is the baseline safety story, and it is conventional. What is less conventional is the set of interactive primitives the project treats as first-class product surface, each with its own architecture decision record under docs/adr/. The first is a secure credential card: a key, password, OTP or payment field is typed into a card that flows straight to the gateway and, per the README, never reaches the model, the transcript or the audit trail. The second is browser sign-in handoff, where the agent gives you a live view of its own browser so you can complete a step it cannot, then resumes. The third is a choice prompt, offered when more than one path is reasonable, so the agent does not silently commit. The fourth is confirm-before-send: before it sends a message, replies, posts or buys on your behalf, it shows what is about to happen and a single button to send it. These are the parts of the project worth judging, because they determine whether an autonomous agent is tolerable to live with. The README states the same cards render on web and iOS off one wire protocol. I cannot verify from the supplied material how the secret path is enforced below the UI layer, so treat that claim as something to check in the source before trusting it with a real payment credential.
Getting an instance running: installer, autostart, and the /setup provider form
The README gives one install command: curl -fsSL https://raw.githubusercontent.com/Open-Curiosity/gini-agent/main/scripts/install.sh | bash. On macOS the installer enables autostart through per-user LaunchAgents for the runtime and the webapp, waits for the webapp to come up, and opens the /setup page in your browser. The form there offers what the README calls the full provider catalog. Provider support is broad and documented per provider under docs/providers/README.md: Codex OAuth; OpenAI, Azure OpenAI, DeepSeek and OpenRouter API keys; the first-party Anthropic Claude API; Amazon Bedrock using model-agnostic Converse with AWS SigV4 (Claude, Nova, Llama, Mistral, DeepSeek); and any OpenAI-compatible local server. Local embeddings, reranking and voice-message speech-to-text are on by default, which matters if you want to avoid sending conversation content to a third party for retrieval. For containers, docs/deployment-docker.md covers running an instance headless with a real browser under Xvfb, which is the path you need if the sign-in handoff feature is going to work on a server with no display. docs/operations.md is where install, start, stop, smoke, diagnostics and cleanup are described. There is also a migration path: docs/migration-from-openclaw.md covers importing an existing openclaw install.
Memory, skill learning, and the human gate that keeps the loop honest
The README advertises that the agent "remembers, improves" and points to docs/memory.md for retain, recall, embeddings, reranking, review and storage, and to docs/skill-learning.md for how it improves its own skills from task outcomes. The skill-learning doc is described as covering a two-tier reward, attribution, a daily review, and a human gate. That last item is the one I would read first. An agent that rewrites its own skills from its own outcomes needs a point where a person confirms the change, or it will drift toward whatever it happened to reward. The presence of a human gate in the design is a good sign, but the README does not describe the gate's mechanics, and I have not run the daily review to see what it proposes or how it is approved. The memory doc similarly names the components (retain, recall, embeddings, reranking, review) without, in the README, specifying the storage backend or how review works. If retrieval quality is the thing you care about, those two documents are the ones to read before installing, not the README.
Where Gini is the wrong tool, and what a framework gives you instead
The clearest limitation is structural: Gini is an application, not a library. If you want to embed an agent loop in an existing Node service, you are adopting a gateway process, a Next.js control plane and a client contract, not importing a function. The README says as much when it claims the project is "built to be a product, not plumbing." That is a deliberate trade, and it costs you the ability to swap the UI or the transport without touching the runtime. The comparison that makes this concrete is a framework such as LangGraph or the Vercel AI SDK. Those give you composable pieces: you define nodes or tool calls, you choose your own persistence, and you own the surface the user sees. Gini gives you the opposite: an opinionated runtime with approvals, memory, jobs, traces and audit events already wired, and a fixed set of client contracts on top. If your agent has no human in the loop, if it runs as a batch job on a schedule and never needs a credential typed in, the inline control primitives are dead weight and you are paying for a control plane you will not open. The other limitation worth naming is maturity. The repository shows three releases between May and June 2026, reaching v0.3.0, and the last push is dated 2026-07-18. That is a young project by any measure, and the README's own framing ("the gaps this project is closing") suggests it is still defining its bar rather than meeting a settled one.
Licence, upgrade cost, and what to verify before you depend on it
The project is MIT-licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is permissive and carries no copyleft obligation, but it also means there is no warranty, and nothing in the licence obliges anyone to keep the runtime compatible with your deployment. The material does not describe a plugin API, a stable extension point, or a compatibility policy across minor versions, so the upgrade cost is not something I can estimate from what is here. What the material does show is a release process with its own conventions: docs/releases.md covers versioning and CHANGELOG conventions, and the roadmap lives in ROADMAP.md with shipped surfaces and planned work. The concrete things to check before depending on this in anything that matters are the state migration story (what happens to conversations, memories and skills when you move from v0.3.0 to the next release), whether the gateway's port and disk layout in docs/gateway.md lets you run the number of instances you need, and whether the secret-handling path described in docs/adr/browser-fill-secret.md and docs/adr/chat-credential-provisioning.md actually keeps credentials out of the transcript as claimed. Those are verifiable by reading the docs and the source. Nothing in the supplied material tells you how many people run it or how it behaves under sustained load, and I would not guess.
Editorial conclusion
Adopt Gini if you want a self-hosted personal agent whose state, memory, jobs and audit trail live in one Bun process you control, and if you value the inline control primitives (secure secret fields, browser sign-in handoff, confirm-before-send) over wiring up a framework yourself. Do not adopt it if you need a stable plugin API, if you are unwilling to run a gateway process and a Next.js app on your own machine or container, or if your use case is a stateless batch job with no human in the loop. Before committing, read docs/memory.md and docs/skill-learning.md and verify the two-tier reward and human gate described there, then run the smoke and diagnostics commands from docs/operations.md against your own provider credentials.
Community notes