8.6 KiB

Raw Blame History

AGENTS.md

Project-level context for AI agents working in this repository.

Project Overview

Ollie is an AI agent runtime inspired by Plan 9: agent state and behaviors are exposed as files in a 9P namespace. Orchestration, scheduling, and UIs are external — shell scripts, editors, web apps. The core is minimal; capabilities come from composing scripts.

Repository Layout

Monorepo with Git submodules. Each submodule has its own Go module (except el which is Elisp and kde which is C++/Qt).

ollie/                          ← you are here
├── core/         (Go)          Core library: agent loop, backends, tools, config
├── 9p/           (Go)          9P filesystem server (olliesrv)
├── dbus/         (Go)          D-Bus session manager daemon (ollied)
├── acme/         (Go)          Plan 9 acme editor frontend
├── httpgw/       (Go)          HTTP-to-9P gateway
├── webui/        (TypeScript)  Preact SPA browser frontend
├── kde/          (C++/Qt6)     KDE integration: plasmoid, standalone GUI, Kate plugin, KRunner, tray
├── el/           (Elisp)       Emacs frontend (ellie.el)
├── agents/                     Agent config JSONs (loaded at runtime)
├── prompts/                    System prompt templates (markdown) ← NOT used; see note below
├── tools/                      Tool scripts (file_read, lsp_*, memory_*, etc.)
├── sandbox/                    Landlock sandbox config YAML
├── scripts/                    User-facing CLI scripts:
│   ├── s/                      Session management (sh, bfg, ls, kill, ...)
│   ├── u/                      Utilities (complete, optimize, cascade)
│   └── x/                      Internal/plumbing (elevate, prime, bd, task)
├── doc/                        Architecture docs, usage guide
├── contrib/                    Community scripts
└── experiments/                Trial notes

Canonical source for prompts/tools/skills

Three locations have prompt and tool files. The source of truth depends on which component you're editing:

Location	Purpose	Deployed by
`9p/prompts/`, `9p/tools/`	Canonical source for the 9P server	`just install-data`
`9p/skills/`, `kde/skills/`	Shared `agent-skills` submodule (same repo in both)	`just install-data`
`kde/prompts/`, `kde/tools/`	KDE-specific copies (may diverge for KDE-only tools like `gui_*`)	`just install-kde`
Root `prompts/`, `tools/`	Top-level copies installed by `just install-data`	`just install-data`

The just install-data target copies agents/, prompts/, tools/, sandbox/ (and skills/ from submodules) into ~/.config/ollie/. Do not edit ~/.config/ollie/ directly — changes are overwritten on next install.

When adding a new prompt/tool that should be available to all frontends, add it to both 9p/prompts/ (or 9p/tools/) and the root prompts/ (or tools/) directory.

Build System

# From monorepo root (pick one):
just              # 9P path (recommended): core, 9p, acme, kde, httpgw, webui, emacs
just dbus         # D-Bus path (KDE-only): core, ollied, kde, httpgw, webui

# Individual build targets:
just core         # core library
just ninep        # 9P server
just acme         # acme frontend
just kde          # KDE integration (cmake with ~/.local prefix)
just httpgw       # HTTP gateway
just webui        # web UI (needs npm)
just dbus-bin     # D-Bus daemon (ollied)

# Install targets (run automatically by the top-level paths):
just install-data     # agents, prompts, tools, skills → ~/.config/ollie/
just install-scripts  # CLI scripts → ~/.config/ollie/scripts/
just install-contrib  # contrib scripts → ~/bin/
just install-kde      # KDE plugins, desktop file, env → ~/.local/
just install-el       # ellie.el → ~/.config/emacs/ellie/
just install-dbus-bin # ollied + autostart → ~/.local/bin/, ~/.config/autostart/

# Test:
just test         # run all tests (core + 9p)
just test-core    # core tests only
just test-9p      # 9p tests only

# Lifecycle:
just uninstall    # remove all installed files
just clean        # remove build artifacts

Requires just: cargo install just

Testing

# Go tests (from any Go submodule):
go test ./...

# Core has the most tests:
cd core && go test ./...

# 9P server tests:
cd 9p && go test ./...

# KDE has integration test scripts:
cd kde && ./test-e2e.sh

Language & Conventions

Go (core, 9p, dbus, acme, httpgw): Go 1.25+, standard library preferred, minimal dependencies. Modules are ollie (core), olliesrv (9p), ollie-dbus, ollie-acme, ollie-httpgw.
C++20/Qt6/KF6 (kde): CMake build, dual Qt5/Qt6 support where noted.
TypeScript (webui): Vite + Preact.
Elisp (el): single file ellie.el.
Tool scripts: Python 3 or Bash. Must be executable. Header comments declare metadata (# ollie:parallel read, # ollie:tier cold, # description:, # args:).

Code style

Go: gofmt, short variable names, error returns (no panics), table-driven tests.
Tool scripts: emit structured output (STATUS=ok, STATUS=error). Image/LSP tools return JSON content blocks.
Prompts: markdown, concise, example-driven. Follow the pattern in existing tools-*.md files.

Architecture (key concepts)

Two integration surfaces: 9P filesystem (sessions at s/{name}/) and D-Bus (org.ollie.SessionManager). Tools, skills, memory on physical filesystem via env vars.
Agent loop (core/pkg/agent/): Streaming LLM call → parse tool calls → dispatch → loop until no more tool calls or max steps.
Tool dispatch (core/pkg/tools/): shell is built-in. All others are external scripts resolved from OLLIE_TOOLS_PATH.
Sandbox (core/internal/sandbox/): Landlock-based. Config in sandbox/*.yaml defines filesystem access per profile.
Backends (core/pkg/backend/): Ollama, OpenAI-compatible, Anthropic, Copilot, Kiro. Selectable per-session.
Prompts assembled at runtime: Agent JSON prompt array runs shell commands (via x/prime) that cat markdown files together. No static prompt file is used directly.
D-Bus (kde/dbus only): ollied exposes org.ollie.SessionManager for KDE frontends. It's a separate daemon from olliesrv.

Key Files

What	Where
Agent loop	`core/pkg/agent/loop.go`
Tool dispatcher	`core/pkg/tools/execute/`
Remote execution client	`core/pkg/remote/remote.go`
Remote execution server	`remote/main.go`
Sandbox enforcement	`core/internal/sandbox/`
9P filesystem	`9p/fs/`
Session management	`9p/session/`
System prompt template	Embedded in binary (`system_prompt.md`)
Agent configs	`agents/*.json`
D-Bus daemon	`dbus/main.go`
KDE D-Bus client	`kde/plasmoid/plugin/olliedbusclient.cpp`
Standalone GUI	`kde/gui/`
Kate plugin	`kde/kate/`

Environment

Config lives in ~/.config/ollie/env. Key variables:

OLLIE_BACKEND — default backend (ollama, openai, anthropic, copilot, kiro)
OLLIE_MODEL — default model
OLLIE_TOOLS_PATH — where tool scripts live (default: ~/.config/ollie/tools)
OLLIE_MEMORY_PATH — persistent memory directory
OLLIE_ENABLED_BACKENDS — backends available for routing

Adding a new tool

Create an executable script in tools/ (and 9p/tools/, kde/tools/ if needed)
Add header comments: # description:, # args:, optionally # ollie:parallel read or # ollie:tier cold
Create a matching prompts/tools-*.md documentation file (and in 9p/prompts/, kde/prompts/)
Run just install-data to install

Adding a new prompt

Write the markdown file in 9p/prompts/ and root prompts/
If it should be loaded by default, add a $OLLIE_CFG_PATH/scripts/x/prime <name> entry to agents/default.json
Run just install-data to install

Submodule workflow

# Update all submodules:
git submodule update --remote --merge

# Work in a submodule (e.g., core):
cd core
# ... make changes, commit ...
git push
cd ..
git add core
git commit -m "update core submodule"

Each submodule has its own remote at ssh://lkn@lneely.de:44220/lkn/ollie-{name}.git.

Nested submodules

Both 9p/ and kde/ contain a nested skills/ submodule pointing to the same repo (agent-skills.git). There is no root-level skills/ directory.

9p/skills/   → ssh://lkn@lneely.de:44220/lkn/agent-skills.git
kde/skills/  → ssh://lkn@lneely.de:44220/lkn/agent-skills.git  (same repo)

When cloning, use --recurse-submodules or run git submodule update --init --recursive to get these.

8.6 KiB Raw Blame History