Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Effectful-Tech/clanka/llms.txt

Use this file to discover all available pages before exploring further.

Clanka is published to npm as an ES module and has five required peer dependencies, all from the Effect ecosystem. This page covers installing everything and wiring up your TypeScript project so compilation succeeds.

​
Install clanka

pnpm add clanka

​
Install peer dependencies

Clanka requires five peer packages. All five must be on the same compatible version range. Install the exact range shown below. 
pnpm add \
  "effect@>=4.0.0-beta.52 <4.0.1" \
  "@effect/ai-openai@>=4.0.0-beta.52 <4.0.1" \
  "@effect/ai-openai-compat@>=4.0.0-beta.52 <4.0.1" \
  "@effect/platform-node@>=4.0.0-beta.52 <4.0.1" \
  "@effect/sql-sqlite-node@>=4.0.0-beta.52 <4.0.1"

​
What each peer dependency provides

PackageVersion rangePurpose
effect>=4.0.0-beta.52 <4.0.1Core Effect runtime — fibers, layers, streams, schemas, and the full FP toolkit Clanka is built on
@effect/ai-openai>=4.0.0-beta.52 <4.0.1OpenAI-compatible language model and client layers; used by the Codex provider
@effect/ai-openai-compat>=4.0.0-beta.52 <4.0.1OpenAI-compatible shim layer; used by the Copilot provider to talk to GitHub’s API
@effect/platform-node>=4.0.0-beta.52 <4.0.1Node.js implementations of FileSystem, HttpClient, ChildProcessSpawner, and WebSocket — required by Agent.layerLocal
@effect/sql-sqlite-node>=4.0.0-beta.52 <4.0.1SQLite driver for Node.js; required by the semantic search layer to persist the vector index
All five packages must resolve to versions within the same compatible range (>=4.0.0-beta.52 <4.0.1). Mismatched versions will cause Effect context errors at runtime because service identity is based on the effect module’s internal symbol registry.
Clanka ships optional native binaries that power the vector similarity search used by the SemanticSearch layer. These are installed automatically by your package manager on supported platforms, but they are not required if you do not use semantic search. The supported platforms are:
  • macOS arm64 (@sqliteai/sqlite-vector-darwin-arm64)
  • macOS x86-64 (@sqliteai/sqlite-vector-darwin-x86_64)
  • Linux arm64, glibc (@sqliteai/sqlite-vector-linux-arm64)
  • Linux arm64, musl (@sqliteai/sqlite-vector-linux-arm64-musl)
  • Linux x86-64, glibc (@sqliteai/sqlite-vector-linux-x86_64)
  • Linux x86-64, musl (@sqliteai/sqlite-vector-linux-x86_64-musl)
  • Windows x86-64 (@sqliteai/sqlite-vector-win32-x86_64)
If you are installing in a CI environment or a Docker image and want to skip the native binaries entirely, pass --ignore-optional / --no-optional to your package manager.

​
Configure TypeScript

Clanka is published as an ES module and uses TypeScript path-based imports (e.g., "./Agent.ts"). Your tsconfig.json must use a module resolution strategy that supports these patterns. 
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "bundler",
    "strict": true,
    "verbatimModuleSyntax": true
  }
}
moduleResolution: "bundler" works with bundlers such as esbuild, Vite, and Bun, as well as with tsx for running TypeScript directly. If you compile with tsc alone and target Node.js directly, use "moduleResolution": "node16" with "module": "node16" instead.

​
Required settings

OptionRecommended valueWhy
targetES2022 or higherClanka uses top-level await, private class fields, and using declarations
moduleResolutionbundler or node16Needed to resolve .ts extension imports inside the package
verbatimModuleSyntaxtrueKeeps import type and import distinct — required by Effect’s tree-shaking assumptions

​
Verify the installation

Create a small smoke-test file to confirm that types resolve correctly: 
import { Agent, Codex } from "clanka"
import { Layer } from "effect"

// If this compiles without errors, your installation is correct.
const _check: Layer.Layer<Agent.Agent> = Agent.layer
Run it through your type-checker: 
npx tsc --noEmit
If you see no errors, you are ready to build your first agent.

​
Next steps

Quickstart

Build and run your first Clanka agent end to end.

Copilot provider

Use GitHub Copilot as the model provider instead of Codex.

Semantic search

Set up the SQLite vector index for meaning-based code search.

Custom tools

Expose additional functions to the agent sandbox beyond the built-in set.

Build docs developers (and LLMs) love

Get started for freeTalk to us