Skip to content

README.md

Latest commit

 

History

History
425 lines (333 loc) · 14.5 KB

README.md

File metadata and controls

425 lines (333 loc) · 14.5 KB

Gokin

Release Stars Downloads License Go Version

Gokin Demo

🤖 AI-powered coding assistant for your terminal
GLM · MiniMax · Kimi · Ollama — 100% open source

Install • Quick Start • Why Gokin? • Features • Providers • Config • Contribute

✨ Why Gokin?

Most AI coding tools are closed-source, route your code through third-party servers, and give you zero control over what gets sent to the model. Gokin was built with a different goal: a fast, secure, zero-telemetry CLI where your code goes directly to the provider you chose — and nothing else leaves your machine.

Gokin focuses on a small, well-tested set of providers: GLM, MiniMax, Kimi (via Anthropic-compatible APIs) and Ollama (fully local). Secrets, credentials, and sensitive code are automatically redacted before reaching any model, TLS is enforced on every connection, and no proxy or middleware ever touches your data.

Feature Gokin Claude Code Cursor
Price Free → Pay-per-use $20+/month $20+/month
Providers 4 (GLM, MiniMax, Kimi, Ollama) 1 (Claude) Multi
Offline ✅ Ollama ❌ ❌
50 Tools ✅ ~30 ~30
Multi-agent ✅ 5 parallel Basic ❌
Direct API ✅ Zero proxies ✅ ❌ Routes through Cursor servers
Security ✅ TLS 1.2+, secret redaction (24 patterns), sandbox, 3-level permissions Basic Basic
Open Source ✅ ❌ ❌
Self-hosting ✅ ❌ ❌

Choose your price tier:

Stack Cost Best For
Gokin + Ollama 🆓 Free Privacy, offline, no API costs
Gokin + GLM ~$3/month (Coding Plan) Daily coding, best budget value
Gokin + MiniMax Pay-per-use 200K context, strong coding
Gokin + Kimi Pay-per-use Fast reasoning, 256K context

🚀 Installation

One-liner (recommended)

curl -fsSL https://raw.githubusercontent.com/ginkida/gokin/main/install.sh | sh

From source

git clone https://github.com/ginkida/gokin.git
cd gokin
go build -o gokin ./cmd/gokin
./gokin --setup

Requirements

  • Go 1.25+ (build from source)
  • One AI provider (see Providers below)

⚡ Quick Start 

# Launch with interactive setup
gokin --setup

# Or set API key and run
export GOKIN_GLM_KEY="your-glm-key"
gokin

Then just talk naturally:

> Explain how auth works in this project
> Add user registration endpoint with validation
> Run the tests and fix any failures
> Refactor this module to use dependency injection
> Create a PR for these changes

🎯 Key Features

🧠 Smart Code Understanding

  • Multi-file Analysis — Understand entire modules via grep + glob + read
  • Session Memory — Auto-summarizes your session (files, tools, errors, decisions). Survives context compaction. Optional LLM-based summarization every 3rd extraction.
  • Context-aware agents — Read-only tools run in parallel, write tools serialized

📝 Multi-Layer Project Instructions

Priority:  Low ──────────────────────────────── High
           Global → User → Project → Local

Global:    ~/.config/gokin/GOKIN.md
User:      ~/.gokin/GOKIN.md
Project:   ./GOKIN.md, .gokin/rules/*.md
Local:     ./GOKIN.local.md (git-ignored)
  • All layers merged automatically
  • @include directive: @./path, @~/path, @/absolute/path
  • File watching with auto-reload on changes

⚒️ 50 Built-in Tools

  • Files: read, write, edit, diff, batch, copy, move, delete
  • Search: glob, grep, tree
  • Git: status, commit, diff, branch, log, blame, PR
  • Run: bash, run_tests, ssh, env
  • Plan: todo, task, enter_plan_mode, coordinate
  • Memory: memorize, shared_memory, pin_context
  • Parallel execution: Read-only tools (read, grep, glob) run in parallel when model calls multiple

🤝 Multi-Agent System

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Explore  │────▶│   General   │────▶│    Bash    │
│  (read)    │     │   (write)   │     │  (execute) │
└─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │
       └───────────────────┴───────────────────┘
                         │
                  [Progress UI]
  • Up to 5 parallel agents
  • Shared memory between agents
  • Automatic task decomposition
  • API retry with exponential backoff — agents survive transient API errors (rate limits, timeouts, 500s)
  • Provider failover — agents automatically try fallback providers when primary fails
  • Real-time streaming — agent output streamed to UI as it's generated
  • Git worktree support — parallel branch work with isolated sessions

💰 Cost Tracking

  • Per-model pricing for GLM, MiniMax, Kimi models (Ollama is free)
  • Real-time cost in status bar ($0.0243)
  • Per-response cost in message footer
  • /cost and /stats commands with accurate model-specific pricing

🔄 Prompt Caching

  • Explicit cache_control breakpoints for MiniMax and Kimi
  • System prompt, tools, and conversation prefix cached — up to 90% input cost savings
  • Cache break detection with efficiency tracking

🛡️ Safety & Permissions

  • 3-level permissions: Low (auto), Medium (ask once), High (always ask)
  • Sandbox mode for bash commands
  • Diff preview before applying changes (single-file and multi-file)
  • Undo/Redo for all file operations
  • Audit logging
  • Proactive context compaction — predicts token growth and compacts before hitting model limits

🔒 Security & Privacy

Zero Proxies — Your Code Goes Nowhere Except the LLM

┌──────────┐          ┌──────────────────┐
│  Gokin   │ ──TLS──▶ │  Provider API    │
│  (local) │          │  (Z.AI / Kimi /  │
│          │ ◀──TLS── │   MiniMax / ...) │
└──────────┘          └──────────────────┘

No middle servers. No Vercel. No telemetry proxies.
Your API key, your code, your conversation — direct.

Some CLI tools route requests through their own proxy servers (Vercel Edge, custom gateways) for telemetry, analytics, or API key management. Gokin does none of this. Every API call goes directly from your machine to the provider's endpoint. You can verify this — it's open source.

Secret Redaction in Terminal Output

LLM tool calls can accidentally expose secrets found in your codebase. Gokin automatically redacts them before they reach the model or your terminal:

Category Examples
API keys AKIA..., ghp_..., sk_live_..., AIza...
Tokens Bearer tokens, JWT (eyJ...), Slack/Discord tokens
Credentials Database URIs (postgres://user:pass@...), Redis, MongoDB
Crypto material PEM private keys, SSH keys

24 regex patterns, applied to every tool result and audit log. Handles any data type — strings, maps, typed slices, structs. Custom patterns supported via API.

Defense in Depth

Layer What it does
TLS 1.2+ enforced No weak ciphers, certificate verification always on
Sandbox mode Bash runs in isolated namespace (Linux), safe env whitelist (~35 vars) — API keys never leak to subprocesses
Command validation 50+ blocked patterns: fork bombs, reverse shells, rm -rf /, credential theft, env injection
SSH validation Host allowlist, loopback blocked, username injection prevention
Path validation Symlink resolution, directory traversal blocked, TOCTOU prevention
SSRF protection Private IPs, loopback, link-local blocked; all DNS results checked
Audit trail Every tool call logged with sanitized args

Keys Stay Local

  • API keys loaded from env vars or local config (~/.config/gokin/config.yaml)
  • Keys are masked in all UI displays (sk-12****cdef)
  • Keys are never included in conversation history or tool results
  • Ollama mode: zero network calls — fully airgapped

💾 Memory That Persists

> Remember we use PostgreSQL with pgx driver
> What were our database conventions?
  • Project-specific memories
  • Auto-inject relevant context
  • Stored locally (your data stays yours)

☁️ Providers

Important

Recommended providers: Gokin ships with a focused set of 4 providers. Daily-driver confidence is highest on:

  • GLM Coding Plan (GLM-5 / GLM-5.1) — recommended, budget option (~$3/month)
  • MiniMax (M2.7 / M2.5) — recommended for coding, 200K context

Kimi and Ollama also work end-to-end; pick whichever matches your workflow.

Provider Models Auth Notes
GLM ⭐ glm-5.1, glm-5, glm-4.7 API key Budget-friendly coding plan, thinking mode supported
MiniMax ⭐ M2.7, M2.7-highspeed, M2.5, M2.5-highspeed API key 200K context, strong on agentic coding
Kimi k2.5, k2-thinking-turbo, k2-turbo API key Fast reasoning, 256K context
Ollama Any local model None 100% offline, no network calls

All cloud providers use Anthropic-compatible APIs and share the same client (internal/client/anthropic.go) — fewer moving parts, consistent behavior. Ollama uses its own native client.

Switch anytime:

> /provider glm
> /model glm-5.1
> /provider minimax
> /model M2.7
> /provider ollama
> /model llama3.2

⌨️ Commands

Command Description
/login <provider> <key> Set API key
/provider <name> Switch provider
/model <name> Switch model
/plan Enter planning mode
/save / /load Session management
/commit [-m "msg"] Git commit
/pr --title "..." Create GitHub PR
/undo Undo last file change
/theme Switch UI theme
/help Show all commands

Keyboard Shortcuts

Key Action
Enter Send message
Ctrl+C Interrupt
Ctrl+P Command palette
↑/↓ History
Tab Autocomplete
? Show help

⚙️ Configuration

Location: ~/.config/gokin/config.yaml

Minimal

api:
  glm_key: "your-glm-key"
  active_provider: "glm"
model:
  name: "glm-5"

Full Reference

api:
  glm_key: ""
  minimax_key: ""
  kimi_key: ""
  ollama_key: ""                 # optional, only for remote Ollama with auth
  active_provider: "glm"
  ollama_base_url: "http://localhost:11434"
  retry:
    max_retries: 10
    retry_delay: 1s
    http_timeout: 120s
    stream_idle_timeout: 30s
    providers:
      glm:
        http_timeout: 5m
        stream_idle_timeout: 180s
      minimax:
        http_timeout: 5m
        stream_idle_timeout: 120s
      kimi:
        http_timeout: 5m
        stream_idle_timeout: 120s

model:
  name: "glm-5"
  temperature: 0.7
  max_output_tokens: 131072
  enable_thinking: false          # GLM / compat-API extended thinking
  thinking_budget: 0              # 0 = auto (8192 for GLM 4.7+/5.x when thinking enabled)
  force_weak_optimizations: false # opt Strong-tier models into weak-tier safeguards

tools:
  timeout: 2m
  model_round_timeout: 5m
  bash:
    sandbox: true
  allowed_dirs: []

permission:
  enabled: true
  default_policy: "ask"           # allow, ask, deny

plan:
  enabled: true
  require_approval: true

ui:
  theme: "dark"                   # dark, macos, light
  stream_output: true
  markdown_rendering: true

🏗️ Architecture 

gokin/
├── cmd/gokin/          # CLI entry point
├── internal/
│   ├── app/            # Orchestrator & message loop
│   ├── agent/          # Multi-agent system
│   ├── client/         # AnthropicClient (compat) + OllamaClient
│   ├── tools/          # 50 built-in tools
│   ├── ui/             # Bubble Tea TUI
│   ├── config/         # YAML config
│   ├── permission/     # 3-level security
│   ├── memory/         # Persistent memory
│   └── ...

~120K LOC • 100% Go • Production-ready

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for:

  • Development setup
  • Code style guide
  • Pull request process
# Dev setup
git clone https://github.com/ginkida/gokin.git
cd gokin
go mod download
go build -o gokin ./cmd/gokin

# Test
go test -race ./...

# Format
go fmt ./...
go vet ./...

📝 License

MIT — Use freely, modify, distribute.

🙏 Acknowledgments

Made with ❤️ by developers, for developers