cog-code

Browser-compatible coding agent library — LLM + virtual FS + pluggable bash execution.

Install

npm install kvakk-code   # or your package manager of choice

Quickstart

Node.js agent with real filesystem and bash

import { Agent, NodeJSFS, NodeJSBashProvider, createBashTool } from 'kvakk-code'
import { OpenAILLM } from 'kvakk-code'

const agent = new Agent({
  llm: new OpenAILLM({ apiKey: process.env.OPENAI_API_KEY }),
  fileSystem: new NodeJSFS(),
  cwd: process.cwd(),
  bashProviders: [new NodeJSBashProvider()],
})

for await (const event of agent.chat('List all TypeScript files')) {
  if (event.type === 'text_delta') process.stdout.write(event.delta)
}

Browser agent with in-process bash (no server required)

import { Agent, createJustBashSetup } from 'kvakk-code'

const { fileSystem, bashProvider } = createJustBashSetup({
  files: {
    '/src/index.ts': 'export const hello = "world"',
    '/package.json': '{"name": "my-app"}',
  },
})

const agent = new Agent({
  llm: myLLM,
  fileSystem,
  bashProviders: [bashProvider],
})

createJustBashSetup() uses the just-bash package — pure TypeScript, in-process, 70+ built-in commands (ls, grep, sed, awk, jq, etc.). Works in browser and Node.js. No containers, no HTTP calls.

No bash (read/write/edit tools only)

const agent = new Agent({
  llm: myLLM,
  fileSystem: new InMemoryFS({ '/hello.txt': 'world' }),
  // omit bashProviders — no Bash tool is registered
})

Filesystem backends

| Class | Description | Browser | Node.js | |---|---|---|---| | InMemoryFS | Map-backed in-memory FS. Use for tests, demos, and browser playgrounds. | ✓ | ✓ | | NodeJSFS | Wraps node:fs/promises. Use for CLI and server environments. | ✗ | ✓ | | JustBashFileSystem | Backed by the same just-bash Bash instance as JustBashProvider. Use createJustBashSetup() — never construct directly. | ✓ | ✓ |

Bash backends

| Class | Description | Browser | Node.js | |---|---|---|---| | NodeJSBashProvider | child_process.spawn — real system shell. | ✗ | ✓ | | JustBashProvider | just-bash in-process bash — 70+ built-in commands. Use createJustBashSetup(). | ✓ | ✓ |

Pluggable command registry

Multiple providers can coexist. Specific-command providers always beat catch-alls:

import { createBashTool } from 'kvakk-code'

// Hypothetical: pyodide handles python/pip, justbash handles everything else
const bashTool = createBashTool([
  new PyodideProvider(['python', 'python3', 'pip']),
  new JustBashProvider(bash),  // catchall
])

Built-in tools

The agent always has Read, Write, Edit, Glob, Grep, Agent, and TodoWrite.
Bash is opt-in via bashProviders.

Streaming events

for await (const event of agent.chat('Refactor src/utils.ts')) {
  switch (event.type) {
    case 'text_delta':    process.stdout.write(event.delta); break
    case 'tool_start':    console.log(`[${event.name}] ${event.activityDesc}`); break
    case 'tool_end':      console.log(`→ done`); break
    case 'agent_progress': /* sub-agent activity */ break
    case 'turn_end':      console.log(`stop: ${event.stopReason}`); break
  }
}

Development

npm test           # run all tests (vitest)
npm run test:watch # watch mode
npm run typecheck  # tsc --noEmit
npm run build      # build library + CLI

CLI

npm run build
node dist/cli.js --help
node dist/cli.js "list all TypeScript files in src/"