A clean-room Go implementation of an AI-powered agentic CLI tool
| Feature | Description | |
|---|---|---|
| 🤖 | Multi-Provider LLM Support | Native support for Anthropic, OpenAI, Gemini, Kimi/Moonshot, and LiteLLM-compatible endpoints |
| 🔧 | Extensible Tool System | Built-in tools (Read, Write, Edit, Bash, Glob, Grep) with a clean Tool interface for custom tools |
| 💬 | Interactive REPL | Terminal UI with streaming responses, slash commands, and multi-turn conversation |
| 🔄 | Agentic Loop | Autonomous tool execution loop with configurable iteration limits and context management |
| 🛡️ | Permission System | Four modes: auto, approve, deny, and bypass -- fine-grained control over tool execution |
| 🔌 | MCP Client Integration | Model Context Protocol client for connecting to external tool servers |
| 🪝 | Hook System | Pre/post tool execution hooks for custom validation, logging, and side effects |
| 🧠 | Persistent Memory | File-based memory system that persists context across sessions |
| 👥 | Team/Swarm Coordination | Multi-agent orchestration with task delegation and parallel execution |
| 📦 | Plugin Architecture | Modular skill system for extending GoCode with custom capabilities |
- Go 1.22 or later
- An API key from any supported provider (Anthropic, OpenAI, Google, Kimi/Moonshot)
# Clone the repository
git clone https://github.com/newtontech/GoCode.git
cd GoCode
# Build
make build
# The binary is now at ./bin/gocode# Set your API key via environment variable (Anthropic)
export GOCODE_API_KEY="sk-ant-..."
# Or use Kimi/Moonshot (recommended for coding)
export ANTHROPIC_BASE_URL="https://api.kimi.com/coding"
export ANTHROPIC_AUTH_TOKEN="sk-kimi-..."
export ANTHROPIC_MODEL="kimi-k2.5"
export ENABLE_TOOL_SEARCH=false
# Or create a settings file
mkdir -p ~/.gocode
cat > ~/.gocode/settings.json << 'EOF'
{
"apiKey": "sk-ant-...",
"model": "claude-sonnet-4-20250514",
"maxTokens": 16384,
"permissionMode": "auto"
}
EOF# Start the interactive REPL
./bin/gocode
# Or run with a one-shot prompt
./bin/gocode --prompt "Explain the project structure"+=========================================+
| CLI / REPL |
| (cobra + terminal UI) |
+=========================================+
| Agentic Engine |
| (orchestrates LLM <-> Tool loop) |
+=========+=========+=========+===========+
| LLM | Tools |Permission| History |
| Client | System | System | Manager |
+=========+=========+=========+===========+
| Config & Memory & Hooks |
| (layered settings + persistence) |
+=========================================+
| MCP & Plugin Extensions |
| (external servers + custom skills) |
+=========================================+
- User input enters through the CLI or REPL
- The Engine sends the conversation to the LLM Client
- The LLM may request tool execution (e.g., read a file, run a command)
- The Permission System checks if the tool call is allowed
- The Tool System executes the tool and returns results
- Results are fed back to the LLM, and the loop repeats
- This continues until the LLM produces a final text response
GoCode/
├── cmd/
│ └── gocode/ # Application entrypoint
│ └── main.go
├── internal/
│ ├── agent/ # Agent/subagent spawning
│ ├── config/ # Configuration loading & hierarchy
│ ├── engine/ # Agentic tool execution loop
│ ├── history/ # Conversation history & context builder
│ ├── hooks/ # Pre/post tool execution hooks
│ ├── llm/ # Multi-provider LLM client (Anthropic, OpenAI, Gemini, Kimi)
│ ├── mcp/ # Model Context Protocol client
│ ├── memory/ # Persistent file-based memory
│ ├── permission/ # Permission system (auto/approve/deny)
│ ├── repl/ # Interactive terminal UI
│ ├── skills/ # Skill system
│ ├── tasks/ # Task management
│ └── tools/ # Built-in tool implementations
├── pkg/
│ └── types/ # Public types (Message, Tool, Config, Permission)
├── docs/ # Documentation website
├── Makefile
├── go.mod
└── PRD.md
GoCode uses a layered configuration system with the following precedence (highest to lowest):
| Priority | Source | Location |
|---|---|---|
| 1 | CLI flags | --api-key, --model, etc. |
| 2 | Environment variables | GOCODE_API_KEY, GOCODE_MODEL |
| 3 | Project settings | .gocode/settings.json |
| 4 | Global settings | ~/.gocode/settings.json |
| 5 | Defaults | Built-in sensible defaults |
{
"apiKey": "sk-ant-...",
"model": "claude-sonnet-4-20250514",
"maxTokens": 16384,
"permissionMode": "auto",
"historyPath": "~/.gocode/history"
}GoCode supports both GOCODE_* and ANTHROPIC_* environment variables (for compatibility with Claude Code):
| Variable | Description |
|---|---|
GOCODE_API_KEY or ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN |
API key for your LLM provider |
GOCODE_MODEL or ANTHROPIC_MODEL |
Model to use (default: claude-sonnet-4-20250514) |
GOCODE_BASE_URL or ANTHROPIC_BASE_URL |
API endpoint (auto-detects provider) |
GOCODE_PERMISSION_MODE |
Permission mode: auto, approve, deny |
GoCode auto-detects the provider based on BASE_URL and MODEL:
- Anthropic:
https://api.anthropic.com(default) - Kimi/Moonshot:
https://api.kimi.com/coding - OpenAI:
https://api.openai.com, Azure OpenAI - Google Gemini:
https://generativelanguage.googleapis.com - LiteLLM: Any LiteLLM-compatible endpoint
Every tool implements the Tool interface:
type Tool interface {
Name() string
Description() string
InputSchema() ToolInputSchema
Execute(ctx context.Context, input json.RawMessage) (*ToolResult, error)
}| Tool | Description |
|---|---|
Read |
Read file contents |
Write |
Write or create files |
Edit |
Make targeted string replacements in files |
Bash |
Execute shell commands with sandboxing |
Glob |
Fast file pattern matching |
Grep |
Content search with regex support |
Create your own tool by implementing the Tool interface:
package mytools
import (
"context"
"encoding/json"
"github.com/newtontech/GoCode/pkg/types"
)
type MyTool struct{}
func (t *MyTool) Name() string { return "my_tool" }
func (t *MyTool) Description() string { return "Does something useful" }
func (t *MyTool) InputSchema() types.ToolInputSchema {
return types.ToolInputSchema{
Type: "object",
Properties: map[string]types.PropertySchema{
"input": {Type: "string", Description: "The input"},
},
Required: []string{"input"},
}
}
func (t *MyTool) Execute(ctx context.Context, input json.RawMessage) (*types.ToolResult, error) {
// Your logic here
return &types.ToolResult{Content: "done"}, nil
}# Build the binary
make build
# Run all tests
make test
# Run linter
make lint
# Clean build artifacts
make clean# Run all tests with verbose output
go test -v ./...
# Run tests for a specific package
go test -v ./internal/engine/
# Run with race detector
go test -race ./...GoCode follows Test-Driven Development (TDD) principles. All new features and bug fixes must include tests:
- Write tests first before implementing functionality (Red-Green-Refactor cycle)
- Use table-driven tests for multiple input/output cases
- Prefer fakes over mocks for dependencies
- Run the full test suite with race detection before submitting changes
- All tests must pass with
go test ./...andgo test -race ./...
This repository contains comprehensive test coverage following TDD principles to ensure code quality and prevent regressions.
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
GoCode is built incrementally. See PRD.md for the full product requirements.
| Phase | Status | Description |
|---|---|---|
| 1. Project Foundation | ✅ Done | Go module, directory structure, core types, config system |
| 2. Core Engine | ✅ Done | LLM client, agentic loop, conversation history |
| 3. Built-in Tools | 🚧 In Progress | File tools, Bash tool, agent spawning |
| 4. CLI & REPL | :planned: Planned | Cobra CLI, interactive terminal UI, permission system |
| 5. Extensibility | :planned: Planned | MCP client, hook system, skill system, plugins |
| 6. Advanced Features | :planned: Planned | Memory system, task management, team/swarm coordination |
Full documentation is available in the docs directory:
- Getting Started -- Installation and setup guide
- Architecture -- Detailed architecture and design decisions
- Tools Reference -- Complete tool documentation
- Configuration -- Configuration reference
- API Documentation -- LLM client API reference
- Extending GoCode -- Plugin and extension development
- Roadmap -- Development roadmap
This project is licensed under the MIT License -- see the LICENSE file for details.
MIT License
Copyright (c) 2025 NewtonTech
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...
Built with ❤️ by NewtonTech