Neko Core

Một chú mèo trong terminal — chỉ muốn meo meo, và làm việc.

Neko Core is a local-first terminal agent for coding and computer work. It combines a provider-agnostic agent loop, durable sessions, governed tools, skills, MCP, browser control, and an Ink terminal UI in one standalone binary. The shipped CLI is written in TypeScript, compiled with Bun, and does not require Bun on the user's machine.

By Meiiie / The Wiii Lab. Download in English or Vietnamese at neko.holilihu.online.

Stable 1.x line. Public CLI, configuration, durable-session, SDK, ACP, authority, and rollback contracts follow the stability and support policy. See the current release for install and upgrade notes.

Why Neko

• A real agent harness. Streaming complete -> tool calls -> observe loop, concurrent safe reads, context relief, compaction, loop recovery, verification debt, and bounded closed-loop continuation. Explicit closed loops fix an observable completion contract before implementation and use an independent validator.
• Local-first and provider-agnostic. Use hosted APIs, supported subscription accounts, or an OpenAI-compatible local server. Models and endpoints are config, not product forks.
• Governed action. Read tools are safe; edits, shell, browser, Office, and host-computer actions pass through one permission boundary. Catastrophic commands and credential targets remain hard refusals.
• Durable work. Sessions checkpoint messages, tool calls, results, provider continuation data, model, profile, and mode. Resume after an interrupt or process restart without silently replaying mutations.
• Terminal-native UX. Fullscreen transcript, live Markdown, smooth scrolling, mouse selection, clickable pickers, multiline input, image paste, completion alerts, and clean terminal restoration on exit.
• Extensible everywhere. Built-in skills ship inside the binary and work from every folder; ~/.neko-core/skills adds global overrides. MCP, recipes, memory, workflows, and ACP extend the same core.
• Auditable delivery. Every release is built for five targets, smoke-tested, checksummed, compressed for transfer, and published by GitHub Actions. Updates checkpoint and resume interrupted downloads; exact-version rollback is supported by both the updater and installers.

Install

One line; no Bun or Node.js required:

# macOS / Linux
curl -fsSL https://neko.holilihu.online/install.sh | sh

# Windows PowerShell
irm https://neko.holilihu.online/install.ps1 | iex

If the domain is unavailable, use the same scripts from https://raw.githubusercontent.com/meiiie/neko-core/main/install.sh or install.ps1. Direct binaries, a smaller Windows ZIP, and their SHA-256 files are on the latest release. The one-line installers automatically prefer the smaller compressed asset and preserve partial progress on an interrupted connection.

Start Neko:

neko

Then use /login, choose a provider and an authentication route, and use /model to select from the catalog available to that account. neko doctor performs read-only setup diagnostics.

Get started under freer auto. Product-default auto is the path to try first: coding tools, outside writes, and computer run without routine prompts; workspace-destructive bash still asks (interactive) or seatbelt-denies with a recoverable observation (neko run). Reach for --yolo / --always-approve only when you intentionally want remaining prompts skipped for that launch — HardMix evidence shows freer auto can finish hard headless work with seatbelts on. See Permissions and the freer-auto HardMix write-up.

Provider routes

Neko keeps account subscriptions and pay-as-you-go API billing visibly separate.

Provider	Supported route
OpenAI	ChatGPT subscription OAuth or OpenAI API key
Google	Gemini API key or Code Assist Standard/Enterprise OAuth through isolated ACP
Anthropic	Anthropic API key
xAI	Grok subscription OAuth or xAI API key
Kimi	Kimi Code account OAuth or Kimi Platform API key
DeepSeek	DeepSeek API key
Z.AI	GLM Coding Plan or paid General API
OpenRouter	API key with live tool-capable model discovery
OpenCode	Console account OAuth or Zen service-account API key
Cline	Cline Account device OAuth or Cline API key
Local/custom	Any configured OpenAI-compatible endpoint, including llama.cpp or Ollama

Neko owns and refreshes its own OAuth state. It does not import another CLI's credential store, mix an account token with API billing, or silently fall back across authentication routes. Credentials are stored outside the transcript and removed from child-process environments.

Non-interactive examples:

neko login openai chatgpt
neko login openai api <key>
neko login google api <key>
neko login xai
neko login xai api <key>
neko login kimi
neko login deepseek <key>
neko login openrouter <key>
neko login opencode
neko login opencode zen <key>
neko login cline account
neko login cline api <key>

Everyday use

neko                         # interactive TUI (product-default auto)
neko --yolo                  # skip remaining approval waits; hard seatbelts still apply
neko --always-approve        # synonym of --yolo (Grok Always-approve map; Ctrl+O stays expand)
neko --resume                # resume the latest session in this folder
neko run "fix the failing tests"          # headless freer-auto; destructive bash still seatbelt-denies
neko run --loop --max-steps 80 "finish the migration and verify it"
neko bench contract hard --trials 3 --call-budget 24
neko bench campaign frontier --profiles zai,bai --trials 3 --call-budget 24
neko acp                     # ACP v1 server for Zed, JetBrains, and other clients
neko acp --host-profile nekocut # exclusive six-tool embedding profile for NekoCut
neko update                  # install latest and resume auto-updates
neko update <version>        # exact rollback/pin; pauses auto-updates

--max-steps <n> (1..512; config default 40) raises the per-round agent step cap for neko run and neko bench (including bench gui). For run/doctor/config it is honored through load(); for bench gui an explicit CLI value overrides each task's built-in horizon (omit the flag to keep per-task caps). Under --loop, hitting the step cap forces at least one closed-loop review even when a required artifact file already exists.

Inside the TUI:

• Shift+Tab cycles default, accept-edits, plan, and auto.
• Esc interrupts the active turn; Ctrl+C clears a draft, then exits on the second press.
• Alt+V pastes an image; Alt+C copies the full draft; Ctrl+O expands tool output.
• /model, /login, /resume, /contract, /memory, /browser, /meeting, /support, and /help expose the corresponding guided surfaces.

Neko plays its short Bubble completion sound after successful background work. Set completion_sound:false in ~/.neko-core/config.json or NEKO_COMPLETION_SOUND=0 for silence.

Permissions and sandboxing

The default auto mode is freer autonomy: ordinary coding tools, outside-project structured writes, and host computer control proceed without routine prompts. Workspace-destructive bash (rm -rf, force-push, sudo, curl|sh, …) still asks once with a warning. Neko auto is an allow-list plus surgical seatbelts — not a Claude or Grok Build LLM classifier. Optional adversarial_check is off by default; OS sandbox is opt-in ("sandbox": true). Seatbelts are not confinement.

Competitor surface	Neko equivalent	Notes
Grok Always-approve / grok --always-approve	neko --yolo or neko --always-approve	Launch-scoped; forces auto and skips remaining prompts while mode stays auto. Shift+Tab away from auto suspends it until you return. Hard credential/system/catastrophic seatbelts remain.
Session “always allow this tool”	Approval box [a]	Per-tool remember for the session; not a global mode.
Grok Ctrl+O = always-approve	Not mapped	Neko Ctrl+O expands tool output. Do not remap.

--yolo / --always-approve remove remaining approval waits for the current launch, but do not disable project trust, credential/system path protection, catastrophic-shell refusal, or validation.

HardMix freer-auto (lived). On Terminal-Bench 2.1 HardMix-12 with glm-5.3 (z.ai), same binary / git a9276e6: product-default auto (no --yolo) scored 12/12 pass@1; same-SHA --yolo scored 11/12 (sole miss regex-chess, model/task correctness — not a seatbelt deny). Under freer auto, destructive-bash seatbelts denied some rm/rm -rf batches on 9/12 tasks; the agent recovered (rewrite without delete / split steps) and still passed. Runners passed --max-steps 80, but at that SHA neko run still used config default 40 (silent no-op; fixed on main). Single trial; not a Claude/Grok classifier claim; prior 7/12 yolo used an older eval binary and is historical only. Write-up: Freer Auto 12, YOLO 11. Same Binary.

Shell and CLI work runs directly through the current host Bash by default; on Windows its child console stays hidden. Neko never drives a terminal through Computer Use as a shell fallback. The permission gate, secret environment scrubbing, project trust, and catastrophic-command seatbelt remain active, but direct-host Bash is not filesystem containment. Set "sandbox": true to opt into the platform OS sandbox, which confines writes and uses bounded network grants. If an explicitly configured sandbox is unhealthy, Neko fails closed instead of silently widening to the host. Run neko policy to inspect the effective boundary. See Sandbox and Architecture.

Browser, Office, meetings, and remote control

• /browser connects a capability-scoped loopback bridge to an explicitly visible Chrome tab. Signed-in browser state remains local; relay clients never receive cookies or browser capabilities.
• /support office installs the optional checksummed Office engine. Typed operations stage, validate, and atomically publish Word, Excel, and PowerPoint changes.
• /meeting records consented local audio, keeps video out, and can install a verified local transcription pack. Notes require timestamp evidence.
• /relay pairs a phone through an outbound, end-to-end-encrypted session without opening a local port.

These surfaces are optional and progressively disclosed. Their contracts live under docs/process.

ACP

neko acp exposes the same agent, tools, permissions, skills, and durable session store over ACP v1. Clients can create, list, load, resume, and close sessions; replay and resume are deliberately distinct. Permission requests map to Neko's named modes rather than bypassing the CLI safety boundary. See Neko over ACP.

Embedding applications can opt into a launch-authorized host profile. The first profile, neko acp --host-profile nekocut, disables native/global tools and accepts only NekoCut's exact MCP-over-ACP surface for that session. Ordinary ACP behavior is unchanged, and an ACP request cannot select or widen the profile after launch.

Configuration

Configuration overlays, lowest to highest precedence:

built-ins < profile preset < ~/.neko-core/config.json < ./.neko-core/config.json < NEKO_* environment

Use neko config, neko profiles, neko doctor, and neko policy to inspect the resolved state. Provider keys may come from their named environment variables or the gitignored user config. A new model or endpoint belongs in a profile; it should not require changing the agent core.

Report a problem

Run /feedback inside Neko to add private notes, review the sharing summary and send to the maintainer. Conversation/tool logs are optional; the full scrubbed attachment can be inspected before sending. Nothing is sent automatically; local JSON and email-draft exports are also available. Scrubbing can miss sensitive content, so review before sharing. The two-screen simplification is unreleased. See feedback and privacy for the recipient and limits.

Develop from source

Development requires Node.js and the stable Bun version pinned by CI:

git clone https://github.com/meiiie/neko-core
cd neko-core
bun install --frozen-lockfile
bun run typecheck
bun test
bun run build

The compiled dist/neko is the primary runtime. node bin/neko-source.cjs is the safe development launcher; it disables project autoload before Bun starts. Do not invoke the internal TypeScript entry directly from an untrusted folder.

The package root is also a side-effect-free Bun/TypeScript library. Hosts inject their own provider and approval gate:

import { Agent, ToolRegistry, type ApprovalGate, type Provider } from "neko-core";

export function createAgent(provider: Provider, root: string, approve: ApprovalGate) {
  const tools = new ToolRegistry(root, "auto", approve);
  return new Agent({ provider, tools });
}

Start with the documentation index, then read the harness architecture, working rules, and testing contract. The public compatibility commitment is in the stability policy. Contributions are described in CONTRIBUTING.md.

Heritage and ownership

Neko Core began with the frozen HackAIthon 2026 Bảng C project at meiiie/bang_c. That repository is historical input, not a runtime dependency. The original Python port is retained under reference/python as a spec; the shipping product is the TypeScript implementation.

The owner and publisher of Neko Core is Meiiie / The Wiii Lab.

License

The core and CLI are AGPL-3.0-only or available under a separate commercial agreement. Independently implemented code under sdk/ is Apache-2.0. The Neko Core name and branding are proprietary and are not granted by either code license. See LICENSING.md, COMMERCIAL-LICENSE.md, and TRADEMARKS.md.