Koder SDK

Koder SDK calls local Koder from JavaScript, TypeScript or Python. Open a workspace session, stream results and control which edits and commands are allowed. Version 0.1.1 uses the MIT license.

Requirements

• Node.js 22.13 or later.
• A compatible Koder CLI installation and runtime. The SDK checks ~/.koder-cli/current first. Set KODER_CLI_ROOT, JavaScript cliRoot or Python cli_root to choose an installation. An invalid explicit path is reported.
• Python 3.9 or later for the Python client, which starts a Node bridge.
• The proprietary KARMENLOOP kernel is distributed separately under its own terms. A source checkout without that runtime cannot execute tasks.

Try it locally

git clone https://github.com/KarmenLoop/koder-sdk.git
cd koder-sdk
npm run build
node examples/custom-provider.mjs

The example uses an in-process provider, writes hello.txt in a temporary workspace, reads it back and cleans up. It makes no model API request, but still needs the CLI and kernel.

python3 -m pip install ./python
python3 python/examples/custom_provider.py

JavaScript and TypeScript

import { createKoder } from "./dist/index.mjs";

const koder = await createKoder({
  workspace: process.cwd(),
  permission: "deny",
});

try {
  const session = await koder.session({ readOnly: true });
  const run = session.send("Explain the main entry point in this project.");
  for await (const event of run) {
    if (event.type === "delta") process.stdout.write(event.text);
  }
  const result = await run;
  console.log(result.status, result.files);
} finally {
  await koder.close();
}

Use query({ workspace, prompt, ...options }) for one turn. Reuse a session for related turns and await each send. Use session.reset() for a new conversation. session.messages contains recorded history.

Python

import asyncio
from koder_sdk import Koder

async def main():
    async with await Koder.create(workspace=".", permission="deny") as koder:
        session = await koder.session(read_only=True)
        result = await session.send("Explain the main entry point.")
        print(result.status, result.text)

asyncio.run(main())

Python options use snake case, such as read_only, cli_root and base_url.

Model settings

The default comes from Koder configuration or KODER_MODEL, KODER_BASE_URL and KODER_API_KEY. You can pass model: { model, baseUrl, apiKey } explicitly. Keep keys in environment variables or a credential store, never in source code.

These variables apply to the SDK. Koder desktop does not read model keys from environment variables or .env files.

Other environment variables

KODER_NODE and KODER_SDK_SERVER select the Node executable and bridge path.