Tarantul: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

tarantul is a lightweight personal AI assistant framework written in TypeScript on the Bun runtime. It supports 25+ LLM providers, a tool-execution agent loop, multi-channel chat (Telegram/Slack/Discord), cron scheduling, a skill system, and an OpenAI-compatible HTTP API. Its defining feature is a real long-term memory: per-session MEMORY.md + dated daily logs + atomic, [[wikilink]]-connected notes, indexed for hybrid keyword + semantic search and auto-consolidated into a knowledge graph the agent builds and traverses itself (src/agent/memory*.ts). It is Bun-native and zero-framework by design.

Commands

bun install                 # install deps
bun test                    # run all tests (coverage on by default via bunfig.toml)
bun test tests/api.test.ts  # run a single test file
bun test -t "name"          # run tests matching a name
bun run typecheck           # tsc --noEmit (strict)
bun run lint                # biome check src tests
bun run format              # biome format --write src tests

bun run start onboard       # create ~/.tarantul/config.yaml + workspace
bun run start agent         # interactive REPL
bun run start agent -m "…"  # one-shot; also accepts piped stdin
bun run start serve         # OpenAI-compatible API server (default :8080) + channels

There is no build step for normal use — Bun executes the TypeScript directly. tsconfig.json sets outDir: ./dist only for tsc output; runtime entry is src/cli/main.ts.

Conventions

• Relative imports use a .js extension even though the files are .ts (required by moduleResolution: bundler + verbatimModuleSyntax). Match this — import { X } from "./foo.js", not "./foo".
• The @/* path alias maps to src/* (tsconfig paths).
• Strict TypeScript with exactOptionalPropertyTypes and noUncheckedIndexedAccess. Indexed access yields T | undefined; optional props cannot be assigned undefined explicitly. The linter (biome) treats unused vars/imports as errors and non-null assertions / any as warnings.
• Bun-native, zero-framework. Use Bun.spawn, Bun.file, Bun.write, Bun.serve(), Bun.which() directly. The HTTP API is a raw Bun.serve() fetch handler — no Express/Hono.