Single Binary · Agent-Native

Lightweight Universal
Conversational Architecture

A universal TypeScript framework you can talk to. Orchestrate a fleet of self-improving agents across servers, browsers, and GPU instances through one observable bus.

Install Luca See Why
luca — agent-native
// memory lives in a queryable db backed by markdown
// contentbase.soederpop.com
const docs = container.feature('contentDb', { rootPath: 'docs' })
 
// the central bus for your agent fleet
const mgr = container.feature('assistantManager')
mgr.add('researcher', { use: ['browserUse', docs] })
mgr.add('coder', { use: ['git', 'proc', 'fs', docs] })
 
// query tasks, assign to the right agent
const tasks = await docs.query(docs.models.Task).where('status', 'todo')
tasks.forEach(task => mgr.assign('coder', task))
 
await mgr.startAll() // a swarm, not a chatbot
0
npm install required
1
Binary — In and Out
20+
Built-in Helpers
∞
Agent Toolkits via use()
Why Luca

Three Ideas That
Change Everything

AI agents today either generate ad-hoc code or fight frameworks that weren't designed for them. Luca assistants build applications using the same components they are made from. They don't just write the code — they live in its runtime.

01

One Introspectable Container

Every Luca app has a single container — features, clients, servers, commands, state, events. Every component describes itself. The human reads the same docs the agent reads. There is one way to do things.

02

Single Binary In, Single Binary Out

Luca ships as a standalone binary. No runtime dependencies, no package manager. Use it to build your project, then compile your project into its own binary with your commands, features, and assistants baked in.

03

Assistants That Swarm

Each assistant can use() any module and inherit its tools. The assistantManager orchestrates many — across servers, browsers, and GPU instances — through one observable bus.

Capabilities

Everything an Agent
Needs to Operate

No imports beyond the container. File I/O, HTTP, databases, git, browser automation, terminal UI, encryption — all typed, all discoverable at runtime.

Assistant Manager

The assistantManager is a central observable bus for your agent fleet. Spin up specialized assistants, route messages between them, watch their state — one coordinator for the whole swarm.

Binary Compiler

Compile your project into a standalone executable. No node, no bun, no npm on the target machine. Your users download one file and run it.

File System & Grep

Read, write, watch, and search your project. fs, fileManager, and grep give your agent full project awareness.

Git Integration

Branch info, status, diff, log. The container knows your repo. The agent knows your repo.

Servers & Clients

Express, WebSocket, IPC, MCP. REST and WebSocket clients. Build APIs and real-time systems from the same container.

Process & VM

Shell commands with proc.exec(). Sandboxed code execution in the VM. Docker, SSH, and RunPod for remote compute.

Observable State

Every helper has reactive state and an event bus. The assistant can watch for changes and act autonomously across the entire system.

Self-Documenting

Every component carries introspection metadata — method signatures, options, events, state shape. luca describe and agents use the same data.

Distributed & Cross-Runtime

Assistants run anywhere — server, browser, RunPod GPU. They talk over WebSocket, IPC, or REST. Same container pattern on Node and in the browser via ESM.

Architecture

One Bus.
Agents Everywhere.

The assistantManager is the observable hub. Assistants discover their tools from the container, talk to each other across transports, and run on any machine.

container
Assistant Manager — Observable Orchestration Bus
Agent
researcher
browserUse, fs · local
Agent
coder
git, proc, fs · local
Agent
ui-agent
dom, state · browser
Agent
gpu-worker
runpod, cuda · remote
connected via WebSocket · IPC · REST
Container Registries
Features
helpers
fs, git, proc, vm, grep, sqlite...
Clients
transports
rest, websocket
Servers
infrastructure
express, websocket, ipc, mcp
Commands
CLI
file-based discovery
primitives
Core
Event Bus
emit, on, once
Core
Observable State
reactive, watchable
Core
Introspection
self-documenting metadata
Core
Binary Compiler
luca bundle → standalone exe
Code

From Swarm
to Standalone Binary

Orchestrate a fleet of agents, wire up infrastructure, compile it all to a single executable.

const mgr = container.feature('assistantManager')
 
// each assistant gets its own tools from the container
mgr.add('researcher', { use: ['browserUse', 'fs'] })
mgr.add('coder', { use: ['git', 'proc', 'fs'] })
mgr.add('reviewer', { use: ['git', 'fs'] })
 
// observe the whole fleet
mgr.on('agent:message', ({ from, to, content }) => { /* ... */ })
mgr.on('agent:stateChange', ({ agent, state }) => { /* ... */ })
 
await mgr.startAll() // launch the swarm
import container from '@soederpop/luca'
 
const browser = container.feature('browserUse', { headed: true })
const assistant = container.feature('assistant', {
systemPrompt: 'You are a web research assistant.',
model: 'gpt-4.1-mini',
})
 
// browserUse injects its tools automatically
assistant.use(browser)
await assistant.start()
 
await assistant.ask('Go to hacker news and tell me the top 3 stories')
// spin up an Express server with endpoints
const app = container.server('express')
 
// endpoints auto-discovered from your files
await app.mountEndpoints()
 
// WebSocket server alongside HTTP
const ws = container.server('websocket')
ws.on('connection', socket => {
socket.send('welcome to luca')
})
 
await app.start() // that's it
# bootstrap a project
$ luca bootstrap my-tool
$ cd my-tool
 
# add your own stuff
$ luca scaffold command analyze
$ luca scaffold feature myCache
$ luca scaffold endpoint status
 
# compile to a single binary
$ luca bundle
 
→ dist/my-tool (standalone, no dependencies)
→ your commands, features, assistants — baked in
Command Line

A CLI That
Understands Your Code

Discover, prototype, serve, and compile — all from your terminal. Your AI assistant uses the same commands.

luca bootstrap my-app
Scaffold a complete project with commands, endpoints, features, docs, and AI assistant config — everything wired up.
luca describe fs
Auto-generated documentation for any feature, client, or server. Methods, options, state, events — all introspected at runtime.
luca eval "container.features.available"
Run arbitrary JavaScript against the live container. Inspect state, test features, explore registries interactively.
luca serve
Start an Express server that auto-discovers your endpoints/ folder. OpenAPI docs and static files included.
luca bundle
Compile your project into a standalone binary. Custom commands, features, endpoints, and assistants — all baked in.
luca console
Drop into a full REPL with the container in scope. Every feature, client, and server at your fingertips.

One Download, Unlimited Potential

No dependencies. No node_modules. Agents that talk to each other out of the box.

$ curl -fsSL https://luca-js.soederpop.com/install.sh | bash click to copy
View on GitHub See the Code