Kako Code

Issues · Releases · 中文

Kako Code is an Agent Harness personal assistant that runs on your machine. The LLM is one component; the harness owns persistent context, tool execution, sub-agents, memory, permissions, workflows, and observability. The CLI command is kako.

What is Kako Code

Kako Code is a terminal-first coding and knowledge agent: it reads and edits files, runs shell commands, calls MCP tools, and decides next steps from tool feedback. Unlike a bare chat API wrapper, it focuses on the execution environment—sessions, approvals, skills, memory, and multi-agent orchestration.

Inspired by modern AI coding agents—including Claude Code, Codex CLI, Gemini CLI, and others—but built with an independent design and its own capability extensions. Thanks to Anthropic, OpenAI, Google, and the teams behind these excellent tools for advancing local agent harnesses; we warmly recommend trying them for the workflows they serve best.

Key Features

• Terminal agent — Read / Write / Edit / Grep / Bash, AskUserQuestion, and tool feedback loops in the CLI
• Multi-agent — Spawn explore / plan / general-purpose sub-agents; background tasks; Agents session page (←)
• Plan & permissions — Plan mode, edit approvals, workspace trust, network allowlists, session allows
• Skills & slash — Agent Skills catalog + / commands; manage installs in Web settings (not a separate kako skill CLI)
• MCP — Register MCP servers in kako web and call them like built-in tools
• Memory — Session transcripts, compact, curated memory; memory settings in the Web UI
• Workflows — Run and confirm workflows from the harness
• Sessions — Rewind, session switch / resume, interrupted-task recovery
• Settings — kako web for providers, MCP, skills, security, and memory
• Local-first — Data under ~/.kako/; macOS .pkg and install scripts via GitHub Releases

Install

Supports macOS / Linux (bash). On Windows, use WSL2.

Prerequisite: Node.js ≥ 20 (LTS recommended) and git.

One-line install (recommended)

curl -fsSL https://raw.githubusercontent.com/KakoAI/Kako-Code/main/scripts/install.sh | bash

Pin a release (replace 0.1.0 with a version from Releases):

curl -fsSL https://raw.githubusercontent.com/KakoAI/Kako-Code/v0.1.0/scripts/install.sh | bash

Default layout after install:

Item	Path
App	~/.kako/app
User config / sessions / memory	under ~/.kako/
CLI	~/.local/bin/kako

Add ~/.local/bin to your PATH if needed:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
kako --version

macOS .pkg (GitHub Release)

Download kako-x.y.z-macos.pkg from Releases, or:

VERSION=0.1.0
curl -LO "https://github.com/KakoAI/Kako-Code/releases/download/v${VERSION}/kako-${VERSION}-macos.pkg"
sudo installer -pkg "kako-${VERSION}-macos.pkg" -target /

From source

git clone https://github.com/KakoAI/Kako-Code.git kako
cd kako
pnpm install
pnpm build
pnpm link:dev    # ~/.local/bin/kako → this repo’s dist

Quick start

kako web          # settings UI: providers, MCP, skills, security, memory
cd your-project
kako              # interactive chat in the current directory

1. Open Settings (kako web) and add a model provider (OpenAI-compatible, Anthropic-style, Volcengine Ark, …).
2. Set it as current and run a connection test.
3. Start kako in a project and ask it to explore the repo.

Example first prompt:

Look at this project and summarize the main directories and how to run it.

Key features

• Harness, not just chat. Sessions, transcripts, slash commands, and a durable home under ~/.kako.
• Terminal UI built for long runs. Streaming answers, tool timelines, approvals, AskUserQuestion pickers, agents panel, rewind, and workflow footers.
• Multi-provider models. Configure providers in the web settings UI; switch without editing ad-hoc env files for every session.
• MCP tools. Connect Model Context Protocol servers and approve tools with session-scoped allows when you choose.
• Skills. Product skills (bundled + user-installed) via the Skill tool and slash flows—separate from contributor .agents/skills.
• Sub-agents. Built-in explore, plan, and general-purpose agents for focused, parallel work while the main thread stays clean.
• Security & permissions. Capability modes, security pipeline, network allowlists, bash risk tiers, and interactive tool approval (including “allow for this session”).
• Memory. File-based facts, optional curated memory, FTS recall, and compaction for long conversations.
• Workflows & background work. Scripted workflows, background agents/tasks, and resume paths for interrupted work.
• Plan mode. Structured planning with plan-file constraints before implementation.
• macOS packaging. Tagged releases build .pkg installers via GitHub Actions.

Upgrade

Upgrades do not delete user data (~/.kako/config, memory, skills, …).

# curl install
curl -fsSL https://raw.githubusercontent.com/KakoAI/Kako-Code/v0.1.0/scripts/upgrade.sh | bash

# or re-run install for the same tag
curl -fsSL https://raw.githubusercontent.com/KakoAI/Kako-Code/v0.1.0/scripts/install.sh | bash

For .pkg installs, install the newer package. For a source checkout: git fetch && git checkout vX.Y.Z && pnpm install && pnpm build.

Uninstall

curl -fsSL https://raw.githubusercontent.com/KakoAI/Kako-Code/main/scripts/uninstall.sh | bash

Non-interactive: KAKO_YES=1 …. Also remove user data: KAKO_PURGE=1 ….

The script detects curl and .pkg installs. Default is to keep ~/.kako user data.

Project layout

kako/
├── apps/web/           # Settings UI
├── apps/desktop/       # Tauri desktop (Phase 2)
├── packages/
│   ├── core/           # Harness: loop, tools, security, memory, MCP, workflows
│   ├── cli/            # Terminal UI + `kako` binary
│   ├── server/         # Local API for settings
│   └── shared/         # Shared types
├── agents/             # Agent YAML + prompts
├── skills/             # Product skills (runtime)
├── .agents/skills/     # Contributor how-tos (not shipped to end users)
└── docs/               # Requirements, architecture, contributor guides

Develop

Requirements: Node.js ≥ 22 (see .nvmrc), pnpm 10.12.1.

git clone https://github.com/KakoAI/Kako-Code.git
cd Kako-Code
pnpm install
pnpm build
pnpm lint
pnpm test
pnpm kako                 # run CLI from the workspace
pnpm services:restart     # settings API :3721 + Vite :5173
pnpm pack                 # macOS pkg (local)

Contributor entry points: AGENTS.md, docs/dev/getting-started.md, docs/dev/engineering-principles.md.

Docs

• Vision
• System architecture
• Getting started (dev)
• Roadmap

Disclaimer

Kako Code is provided “as is”, without warranty of any kind. The project may contain bugs, incomplete features, or security risks. By installing, downloading, or using this software, you acknowledge and accept those risks. To the maximum extent permitted by applicable law, the authors and contributors are not liable for any direct, indirect, incidental, special, consequential, or other damages or losses arising from install, use, misuse, or inability to use this project—including but not limited to data loss, system damage, security incidents, or business interruption.

Intellectual property. If you believe any part of this project’s design, documentation, code, branding, or related materials infringes your rights, please contact the maintainers via GitHub Issues (or another channel the maintainers publish). We will review reports in good faith and, where appropriate, adjust, remove, or otherwise remediate the relevant content or the project as needed.

Nothing in this section limits rights or remedies that cannot be waived under mandatory applicable law. Use of this software is also subject to the MIT License.

License

MIT