golem

Golem (גּוֹלֶם)

Golem is a lightweight, extensible personal AI assistant built with Go and Eino. It allows you to run a powerful AI agent locally effectively using your terminal or through messaging platforms like Telegram.

Golem (גּוֹלֶם): In Jewish folklore, a Golem is an animated anthropomorphic being that is magically created entirely from inanimate matter (specifically clay or mud). It is an obedient servant that performs tasks for its creator.

中文文档

✨ Features

• 🖥️ Terminal User Interface (TUI): A rich, interactive chat experience comfortably within your terminal.

• 🤖 Server Mode: Run Golem as a background service to interact via external channels (currently supports Telegram).

• 🛠️ Tool Use:

  • Shell Execution: The agent can run system commands (safe mode available).
  • File System: Read and manipulate files within a designated workspace.
  • Memory Tools: Read/write long-term memory and append daily diary notes.
  • Web Search & Fetch: Search with Brave API (when configured) and fetch web page content.

• 🔌 Multi-Provider Support: Seamlessly switch between OpenAI, Claude, DeepSeek, Ollama, Gemini, and more.

• Workspace Management: Sandboxed execution environments for safety and context management.

Installation

Download Binary (Recommended)

You can download the pre-compiled binary for Windows or Linux from the Releases page.

Install from Source

go install github.com/MEKXH/golem/cmd/golem@latest

Quick Start

1. Initialize Configuration

Generate the default configuration file at ~/.golem/config.json:

golem init

2. Configure Your Provider

Edit ~/.golem/config.json to add your API keys. For example, to use Anthropic's Claude:

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-4-5-sonnet-20250929"
    }
  },
  "providers": {
    "claude": {
      "api_key": "your-api-key-here"
    }
  }
}

3. Start Chatting

Launch the interactive TUI:

golem chat

Or send a one-off message:

golem chat "Analyze the current directory structure"

4. Run as Server (Telegram Bot)

To use Golem via Telegram:

1. Set channels.telegram.enabled to true in config.json.
2. Add your Bot Token and allowed User IDs.
3. Start the server:

golem run

Configuration

The configuration file is located at ~/.golem/config.json. Below is a comprehensive example:

{
  "agents": {
    "defaults": {
      "workspace_mode": "default", // Options: "default" (~/.golem/workspace), "cwd", "path"
      "model": "anthropic/claude-4-5-sonnet-20250929",
      "max_tokens": 8192,
      "temperature": 0.7
    }
  },
  "channels": {
    "telegram": {
      "enabled": false,
      "token": "YOUR_TELEGRAM_BOT_TOKEN",
      "allow_from": ["YOUR_TELEGRAM_USER_ID"]
    }
  },
  "providers": {
    "openai": { "api_key": "sk-..." },
    "claude": { "api_key": "sk-ant-..." },
    "ollama": { "base_url": "http://localhost:11434" }
  },
  "tools": {
    "exec": {
      "timeout": 60,
      "restrict_to_workspace": true
    },
    "web": {
      "search": {
        "api_key": "YOUR_BRAVE_SEARCH_API_KEY", // Optional
        "max_results": 5
      }
    }
  },
  "gateway": {
    "host": "0.0.0.0",
    "port": 18790,
    "token": "YOUR_GATEWAY_BEARER_TOKEN" // Optional
  },
  "log": {
    "level": "info", // debug | info | warn | error
    "file": "" // Optional log file path
  }
}

Gateway API

When golem run is started, Gateway HTTP endpoints are available:

• GET /health
• GET /version
• POST /chat

POST /chat request example:

{
  "message": "Summarize the latest logs",
  "session_id": "ops-room",
  "sender_id": "api-client"
}

If gateway.token is set, send Authorization: Bearer <token>.

Development

Local Quality Checks

Run these commands before pushing:

go test ./...
go test -race ./...
go vet ./...

If any command fails, fix the issue and rerun all checks.

Branch and PR Workflow

1. Create a focused feature branch: feature/<phase>-<topic>
2. Keep the PR scope small and aligned with one phase/task
3. Open a PR to main and merge only after CI is green

License

MIT