Neko Core
Một chú mèo trong terminal — chỉ muốn meo meo, và làm việc. A local-first, extensible terminal agent that codes, browses, remembers — and through skills, MCP, and an evolving memory grows into new roles, from sourcing goods to driving a browser. Built on TypeScript + Bun + Ink, provider-agnostic, offline-capable.
By The Wiii Lab. MIT-licensed — contributions welcome. neko.holilihu.online — download, in English and Vietnamese.
---
What it is
Neko is a general-purpose agent that acts on your machine from the terminal — it reads, searches, edits, and runs code, drives a browser, and reaches the web. It is config-first (model / provider / policy live in config, not code) and not locked to any single role: coding is what it does out of the box, but its pluggable skills, MCP tools, and memory extend it into whole new domains. It talks to any OpenAI-compatible endpoint — a hosted API (NVIDIA NIM, OpenAI, …) or a local server (llama.cpp llama-server, Ollama), so it works offline.
The foundation
- Streaming agent loop — complete → tool-calls → observe, capped by maxsteps, with live token
streaming, read-only tool fan-out (parallel), a stuck-loop guard, and auto-compaction. Token UX separates the cumulative multi-call turn/session from the last request's actual context; multimodal estimates count decoded images rather than their base64 transport bytes. Stable prompt prefixes and provider cache affinity reduce repeated prefill; the evolving playbook sends a compact index and retrieves full lessons on demand. Experimental adaptiveeffort: true (or NEKOADAPTIVEEFFORT=1) lowers the completion after a productive mechanical read. Leave it off for general-purpose work: unlike a learned history-aware router, this lagged heuristic can mistake the hardest post-read synthesis for an easy step. Enable it only after a representative repeated eval shows no quality regression for your retrieval-heavy workload.
- Tools — readfile · search · glob · ls (safe) and writefile · edit · multiedit ·
bash · computer (approval-gated). search uses ripgrep when present; bash takes a per-call timeout and can run in the background; readfile pages large files and reads images/PDFs. On Windows, computer combines UI Automation, mouse-independent touch, Unicode typing, shortcuts, scrolling, and app/file/URL launch. With vision enabled, a desktop screenshot returns directly to the model as the next observation; text-only drivers can pass the saved capture to a separate vision model. Path-escape is refused.
- Web, a ladder not a cliff — websearch + webfetch work with zero config (DuckDuckGo).
neko setup web upgrades to a private multi-engine SearXNG that Neko wakes on demand and stops when idle (Docker, Ollama-style); neko setup tavily <key wires hosted agent-search with no Docker at all. Its real-browser path uses a persistent Chrome profile by default (sign in once); choose neko setup browser attach for existing Chrome tabs or isolated for disposable tests. Each rung falls back to the next automatically. See docs/process/WEB.md.
- Explicit-tab browser bridge — ask Neko to browse a signed-in site and it offers setup at the point of
need; /browser opens the same flow directly. Neko prepares the extension files, opens the supported Chrome install surface, and starts the authenticated loopback bridge. Until the public Store item ships, Chrome still requires one explicit Load unpacked confirmation; local files alone are never reported as installed or connected. neko browser install remains the non-TUI diagnostic/fallback; users never need a Bun or source-tree command after the one-line installer. After setup, normal neko sessions start the bridge automatically. Its autonomous-attach switch lets the authenticated local Neko session select the active http(s) tab without another click; users can disable it and attach manually. Read/click/type grants are separate, sensitive fields stay blocked, and emergency stop detaches immediately; an AI badge, page marker, and non-destructive tab group make control visible. No cookie or capability is sent through /relay. The public-release bundle, privacy policy, and Chrome Web Store submission checklist live in browser-extension/.
- Verified Office artifacts — Word, Excel, and PowerPoint use a typed optional adapter rather than GUI
coordinate scripts or arbitrary shell strings. Read/help/validate calls are safe; create/edit/render calls remain approval-gated. An edit is staged, applied as one stop-on-error batch, closed, validated, and only then atomically moved into place. Same-file edits require the SHA-256 returned by a fresh inspection. Completion still requires targeted readback and visual evidence because valid OOXML does not prove correct layout or current Excel calculations. Install or remove the optional engine from /support office; Neko never downloads it silently. See docs/process/OFFICE.md.
- Local meeting companion — /meeting opens a consent-first capture surface for audio already playing on