go-magnetar

An AI chat agent with an integrated knowledge base. Chat with any OpenAI-compatible LLM, index documents and web pages into a local vector database, and get answers grounded in your own content.

What it does

• Chat — interactive REPL with multi-turn conversation and automatic context compaction
• Index — /index <file|url> adds documents to your RAG knowledge base (optional)
• Fetch — /fetch <url> retrieves and displays web content as Markdown
• Integrations — Confluence, JIRA, GitHub, GitLab (all optional, disabled by default)

Supported file formats: .md, .txt, .csv, .tsv, .docx, .pdf, .odt, .pptx, .xlsx, .html

Requirements

• Go 1.27+ (or download a pre-built binary)
• API key for any OpenAI-compatible provider (OpenAI, Azure OpenAI, Ollama, etc.)
• Qdrant — only if you want to use the RAG knowledge base (rag.enable: true)

Quick start

1. Install

Option A — pre-built binary:

Download from GitHub Releases and place it in your $PATH.

Option B — go install:

go install github.com/wmentor/go-magnetar/cmd/go-magnetar@latest

Option C — build from source:

git clone https://github.com/wmentor/go-magnetar.git
cd go-magnetar
make build          # binary → bin/go-magnetar

2. Configure

On first run, go-magnetar creates ~/.go-magnetar/config.yml automatically.

Edit it to set your LLM API key and model:

version: "1.0"
language: english
verbose: true
profile: default

profiles:
  default:
    llm:
      base_url: https://api.openai.com/v1
      api_key: $env:OPENAI_API_KEY   # or paste the key directly
      model: gpt-4o
      context: 128000
      temperature: 0.9

For a complete list of options see docs/configuration.md.

3. Run

go-magnetar

This opens the interactive chat REPL. Type a question and press Enter:

> What is the capital of France?
Paris is the capital of France.

> /help
...

> ^D   ← Ctrl+D or /exit to quit

What the agent can do

Beyond answering questions, the agent has access to tools it can call automatically:

The agent picks tools automatically based on your question. You don't need to specify which tool to use.

Using the knowledge base (RAG)

The RAG feature is optional. Enable it when you want the agent to answer questions based on your own documents.

Start Qdrant

docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

Enable RAG in config

Edit ~/.go-magnetar/plugins/rag.yml (created automatically on first run):

rag:
  enable: true
  llm:
    base_url: https://api.openai.com/v1
    api_key: $env:OPENAI_API_KEY
    model: text-embedding-3-small
    vector_size: 1536
  qdrant:
    connstr: http://localhost:6333
    collection: documents

The main ~/.go-magnetar/config.yml already includes plugins/rag.yml via the include directive — no changes to it are needed.

Index documents

go-magnetar
> /index docs/guide.md
> /index https://example.com/article
> /index https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/123456
> /index https://jira.example.com/browse/PROJECT-123

The agent will now search the knowledge base before answering any question.

Chat commands

Use ↑/↓ arrow keys to navigate command history (stored in ~/.go-magnetar-history.json).

Sessions

Save the current conversation to a file and restore it later:

> /session.save /tmp/my-session.json

# Resume later
go-magnetar --session /tmp/my-session.json

Security

The agent can execute shell commands via the exec tool. To stay safe:

• Safety guard — dangerous commands (rm -rf /, sudo, git push, package managers, etc.) are blocked automatically. Enable with guard.enable: true in config.
• Read-only mode — toggle with /readonly to block all file writes and shell modifications for the session.
• Root user — go-magnetar refuses to run as root.
• Sensitive env vars — variables matching patterns like TOKEN, KEY, PASS, SECRET are stripped from the command environment before execution.

See docs/security.md for details.

CLI flags

# Non-interactive (scripting / batch)
go-magnetar -f questions.txt

# Load a saved session
go-magnetar --session session.json

# Use a named profile
go-magnetar -p production

# Run in read-only mode
go-magnetar --read-only

Note: In -f mode, chat commands (/index, /fetch, etc.) are not available. Text preprocessor placeholders like {{date}}, {{uuid}}, {{file:path}} are expanded.

Documentation

• Configuration reference
• Chat commands
• Agent tools
• File format support
• Text preprocessor
• Security
• User manual

License

See LICENSE.