This file is the Claude Code equivalent of
.cursor/rules/*.mdc. It is auto-loaded at conversation start and provides project-level constraints.
When modifying code under src/, the following constraints must not be violated.
- Don't do what the Agent should do — GolemBot does not manage context window, dispatch tools, reason, or set session TTL. All "intelligent" behavior is delegated to the underlying Coding Agent.
- Don't add new core concepts — The framework has only two concepts: assistant directory + Skill. Do not introduce Tool, Blueprint, Registry, Pipeline, or other abstractions.
- Don't put CLI logic in the core library —
cli.tsis a thin shell; it only parses arguments and formats output. All business logic must live inindex.ts/workspace.ts/engine.ts/session.ts/server.ts. - Don't declare Skills in config — The
skills/directory is the single source of truth.golem.yamlonly configures engine, name, and infrastructure settings. - Process invocation is engine-owned — All engines use
child_process.spawn. Do not assume invocation style outside the engine.
- Any signature change to the
Assistantinterface (index.ts) must be verified acrossserver.ts,gateway.ts, andcli.ts. - Any change to the
AgentEngineinterface (engine.ts) must remain compatible with all engines (Cursor, Claude Code, OpenCode, Codex). StreamEventtype changes must verify compatibility withserver.tsSSE output,cli.tsevent handling, andgateway.tsIM message assembly.
| File | Responsibility | Should Not Contain |
|---|---|---|
index.ts |
Public API, concurrency locks, orchestration of workspace/engine/session | Engine implementation details, HTTP logic |
engine.ts |
Engine interface, all engine implementations, stream-json parsing, Skill injection | Session management, config loading |
workspace.ts |
golem.yaml read/write, skills scanning, AGENTS.md generation | Engine invocation, session management |
session.ts |
Session persistence (indexed by sessionKey) | Any other logic |
server.ts |
HTTP service, SSE, auth | Engine implementation details |
gateway.ts |
HTTP API + IM channel orchestration | Engine implementation details |
cli.ts |
Argument parsing, call core API, format output | Business logic |
cli-utils.ts |
CLI formatting helpers (tool display, truncation) | Business logic |
chat()calls with the samesessionKeymust be serialized (KeyedMutex).- Different
sessionKeys can run in parallel. - Do not introduce global locks.
Any substantive change to source files under src/ must:
- Add dedicated tests for the new functionality — passing existing tests is not enough.
- Run
pnpm run testto ensure all unit tests pass. - Run
pnpm run buildto ensure TypeScript compiles.
Location: src/__tests__/<module>.test.ts
Mock Engine Pattern — Unit tests do not call the real Agent. Replace with a mock engine:
async function* mockInvoke(prompt, opts): AsyncIterable<StreamEvent> {
yield { type: 'text', content: 'mock response' };
yield { type: 'done', sessionId: 'mock-session-123' };
}Inject via vi.mock('../engine.js', ...), returning mock engine from createEngine.
pnpm run build # TypeScript compile
pnpm run test # Unit tests (vitest)- Binary:
~/.local/bin/claude - Flags:
-p <prompt> --output-format stream-json --verbose --dangerously-skip-permissions --verboseis required for intermediate stream events- Auth:
claude auth loginorANTHROPIC_API_KEYenv var
- Binary:
~/.local/bin/agent - Flags:
--output-format stream-json --stream-partial-output --force --trust --sandbox disabled --approve-mcps - Uses segmentAccum dedup for
--stream-partial-outputsummary events
- Binary:
opencode(on PATH) - Flags:
run <prompt> --format json - step_finish events are accumulated; single done event emitted on process close
- Binary:
codex(npm:@openai/codex) - Flags:
exec --json --full-auto --skip-git-repo-check [--model X] <prompt> - Resume:
exec resume --json --full-auto --skip-git-repo-check [--model X] <thread_id> <prompt> - Auth:
CODEX_API_KEYenv var (also setsOPENAI_API_KEYfor compatibility) --skip-git-repo-checkis required (GolemBot uses temp dirs)