koko 🦍💻: The Secure & Privacy-First Coding Assistant#
koko is a sandboxed, privacy-first coding assistant for the terminal that connects to LLM providers like Claude, Mistral, or Ollama while ensuring no sensitive data leaves your machine. Built with security and privacy at its core, koko provides least-privilege access to files and shell commands, automatic redaction of secrets/PII, and audit logging for transparency.
Perfect for developers who need agentic coding assistance without compromising security.
🔐 Security & Privacy Features#
Sandboxed Environment#
- Directory allowlist: Restricts file operations to explicitly allowed directories.
- Symlink-safe path resolution: Prevents TOCTOU (Time-of-Check to Time-of-Use) attacks.
- Denied file patterns: Blocks sensitive files like
.env,*.pem, andcredentials.json. - File size limits: Caps reads/writes to prevent abuse (default: 1 MB).
Command Policy#
- Default deny list: Blocks privilege escalation (
sudo,su), remote network commands (ssh,scp), and shell evaluation (eval,source). - User confirmation: Requires explicit approval for every shell command.
- Exec hardening: Enforces
ulimitcaps on CPU, memory, and output size.
Automatic Redaction#
- Secrets: Redacts AWS keys, GitHub PATs, Google API keys, Slack tokens, Stripe keys, JWTs, and PEM private keys.
- PII: Masks emails, US SSNs, phone numbers, credit cards, and public IPv4 addresses.
- Scrubbing: Applies to outbound LLM messages and session logs.
Audit Logging#
- Logs every tool invocation to
~/.koko/audit.jsonlwith timestamps, arguments, and SHA-256 hashes. - Chain verification ensures log integrity.
🤖 Multi-Provider LLM Support#
Connect to your preferred LLM backend:
| Provider | Models | API Key Required | Default Endpoint |
|---|---|---|---|
| Claude | Anthropic models | ✅ (CLAUDE_API_KEY) | Anthropic API |
| Mistral | Mistral models | ✅ (MISTRAL_API_KEY) | Mistral API |
| Ollama | Local models | ❌ | http://localhost:11434 |
Switch models at runtime with :model <name> or configure defaults in ~/.koko/config.toml.
🛠️ Agent Tools#
File Operations#
| Tool | Description |
|---|---|
read_file | Read file contents with offset/limit. |
write_file | Create new files (refuses overwrites unless overwrite=true). |
replace_in_file | Find-and-replace with unique match requirement. |
rename_file | Move/rename files. |
delete_file | Delete files (supports /undo). |
list_dir | List directory contents (recursive option). |
search_files | Search files by pattern with context lines. |
Shell & Memory#
| Tool | Description |
|---|---|
exec_command | Run shell commands (policy-gated, requires approval). |
save_memory | Save persistent memories across sessions. |
delete_memory | Remove stored memories. |
list_memories | List all memories with bodies. |
Planning#
| Tool | Description |
|---|---|
exit_plan_mode | Propose a plan for user approval (plan mode only). |
📂 Project Detection & Memory#
Project Detection#
Scans for marker files (go.mod, package.json, Cargo.toml, etc.) to orient the assistant.
Persistent Memory#
Store cross-session memories in ~/.koko/memory/ with types:
- User: Preferences and role.
- Feedback: Corrections and validated approaches.
- Project: Ongoing work context.
- Reference: Pointers to external systems.
⚡ Interactive REPL Commands#
| Command | Description |
|---|---|
:help | Show available commands. |
:koko | Print the koko mascot. |
:clear | Reset conversation history. |
:history | Show message count. |
:tokens | Show token usage stats. |
:undo | Revert the last file change. |
:run <cmd> | Run a shell command directly. |
:plan | Toggle plan mode (read-only investigation). |
:plays | List installed playbooks. |
🎯 Use Cases#
- Secure Coding Assistance: Get help with code without exposing sensitive files.
- Privacy-First AI: Use LLMs without leaking secrets or PII.
- Auditability: Track all actions with tamper-proof logs.
- Custom Workflows: Extend with playbooks for repetitive tasks.
📌 Why Choose koko?#
- Security-First: Sandboxed environment with least-privilege access.
- Privacy-Focused: Automatic redaction of secrets and PII.
- Multi-Provider: Supports Claude, Mistral, and Ollama.
- Transparent: Audit logs for all actions.
- Extensible: Custom playbooks and persistent memory.
📢 Get Involved#
- GitHub: original-flipster69/koko
- Issues: Report bugs or suggest features.
- Contribute: Add new tools or improve security.