Eko: a TypeScript agent framework for browser and computer workflows

What Eko actually solves for JavaScript teams

Most agent frameworks assume a server process. Eko assumes the place where the work happens might be a browser tab, an extension, or a Node script driving Playwright, and it exposes one interface across all three. The README describes it as a production-ready JavaScript framework that provides a unified interface for running agents in both computer and browser environments. The repository layout backs that up: the workspace declares packages/eko-core, packages/eko-extension, packages/eko-nodejs and packages/eko-web, so the platform split is a packaging decision rather than an abstraction bolted on later.

The audience is narrower than the tagline suggests. This is for developers already inside the TypeScript toolchain who want a natural-language instruction to become an ordered plan with tool calls, not for someone who wants to point a chatbot at a spreadsheet. The README's own example is the shape of the intended use: a single sentence that searches for news, summarizes it, and writes a file to the desktop, handled by a BrowserAgent and a FileAgent working from the same LLM configuration object.

How a sentence becomes a plan: agents, LLMs and task snapshots

The core mechanism visible in the README is a configuration object plus an agent list. You declare named LLM entries, each with a provider, a model and an apiKey, then pass an array of agents and those LLMs into a new Eko instance. Calling run with a string returns a result. Everything else, including which agent handles which step, is the framework's job.

The interesting parts are the controls around that loop. The 3.0 release notes mention dependency-aware parallel agent execution, which means the framework builds a graph of steps and runs independent ones at the same time instead of walking a linear list. The September 2025 notes also add pause, resume and interrupt controls with a task_snapshot workflow recovery mechanism, so a run can be stopped and restored rather than restarted from the beginning. Version 4.0 adds chat conversations and reworks the agent logic.

Two constraints follow from this design. First, the dependency graph format is versioned, and the upgrade guide says saved workflows or exported plans must be regenerated for the v3 schema. Anything you persisted under an older schema is not automatically forward-compatible. Second, the README lists the observable chain as coming soon, so tracing a parallel run is on you for now. That is the honest cost of the concurrency feature.

Installing Eko and running a first browser task

The package installs from npm under the name @eko-ai/eko. The README gives a pnpm command for it.

pnpm install @eko-ai/eko

If you want the shipped examples rather than the library alone, the repository has a workspace layout and the README says to install and build from the root first. The build script runs the package builds sequentially across the workspace.

pnpm install
pnpm build

For a Node.js automation task, the README's example directory is the shortest path to something running. Note that Playwright browsers are installed separately the first time, and at least one model API key must be present in the environment.

cd example/nodejs
pnpm install
pnpm playwright install
pnpm run build
OPENAI_API_KEY=... ANTHROPIC_API_KEY=... pnpm run start

Inside your own code, the LLM object is the piece you will edit most. The README shows a default provider plus named alternatives, including OpenAI-compatible endpoints for models such as Qwen and Doubao, where you set the provider to openai and point config.baseURL at the vendor's compatible endpoint.

const llms: LLMs = {
  default: {
    provider: "anthropic",
    model: "claude-sonnet-4-5-20250929",
    apiKey: "your-api-key"
  }
};

let agents: Agent[] = [new BrowserAgent(), new FileAgent()];
let eko = new Eko({ llms, agents });
let result = await eko.run("Search for the latest news about Musk, summarize and save to the desktop as Musk.md");

What you should see is a completed result object after the browser agent has searched and the file agent has written the markdown file. If the run stalls, the first thing to check is whether the model named default is reachable, since every agent resolves through that configuration.

The API key warning is the most important line in the README

Eko runs in browser extensions and web apps, and that is exactly where credential handling gets dangerous. The README prints a security warning in capitals: do not use API keys in browser or frontend code, because it exposes your credentials and may lead to unauthorized usage. Its stated best practice is to configure a backend API proxy request through baseURL and request headers, with a link to the configuration page for the web environment.

This is not a stylistic note. A framework that advertises browser and extension targets while also accepting an apiKey field in a plain configuration object is one copy-paste away from shipping a key to every visitor. The extension example in the repository asks you to configure your API key in the extension options before running the automation task, which is a local-development convenience rather than a distribution model. If you plan to publish an extension or a web app, the proxy is the only path the documentation endorses.

The second limitation is environmental. The README's development environments list browser extension, web application and Node.js application, and the use cases include system file and process management plus GUI automation. Those capabilities depend on the host granting them. A sandboxed web page cannot manage files the way the Node.js demo can, so the same natural-language instruction can succeed in one environment and fail in another.

Eko compared with LangChain and browser-use

The README includes a comparison table, and its claims are worth reading as positioning rather than measurement. Against LangChain it puts Eko ahead on platform coverage, claiming all platforms versus server side, and marks one-sentence-to-multi-step workflow as supported by Eko but not by LangChain. Against browser-use it claims broader platform support, since browser-use is listed as browser only, and it marks intervenability and task parallelism as Eko features that browser-use lacks.

The genuine difference in approach is where the plan lives. LangChain-style code tends to express a workflow as explicit chains and runnables that you compose, so the control flow is in your source. Eko takes a string and produces the plan at runtime, which is why the comparison table can claim a one-sentence workflow. That trade is real in both directions: you write less orchestration code, and you give up the ability to read the control flow without running it.

The table also lists Dify.ai and Coze, both web platforms, with Coze marked as not open source. If your team wants a hosted interface rather than a library, those are the comparison points, and the difference is deployment model rather than feature count. The table is the project's own summary and does not show the method behind the ratings.

Maintenance, the v4 upgrade cost and the MIT licence

The repository is not archived. The last push was on 2026-03-03, and the most recent release listed is v4.1.0 from 2025-12-29, with v4.0.8 and v4.0.7 both landing on 2025-12-12. The cadence through late 2025 was busy; the gap between that release and the last push is the number to weigh, not a label.

Upgrading across a major version is a documented, multi-step job. The README's Eko 4.0 guide tells you to update four packages with pnpm up (@eko-ai/eko, @eko-ai/eko-nodejs, @eko-ai/eko-web, @eko-ai/eko-extension), regenerate saved workflows or exported plans to the v3 schema and dependency graph format, clean and reinstall with pnpm, then rebuild browser or desktop bundles, and finally re-run automated demos and update documentation for the new pause and interrupt APIs and the parallel agent behavior. The clean script in package.json removes node_modules and each workspace's dist, which is the same operation the guide describes.

Budget for that work if you have persisted plans or a shipped extension. The licence is MIT, which is permissive and places few obligations on how you redistribute the code; it also means there is no warranty, and the README's build status badge points at a placeholder URL rather than a real pipeline. Treat the badge as decoration. Licence terms are a matter for your own counsel, not for this page.

Editorial conclusion

Adopt Eko if you are shipping JavaScript or TypeScript and need one agent loop that covers both a Playwright-driven Node process and a browser extension, and you can keep your model keys behind a proxy. Skip it if you need Python, a hosted control plane, or a framework whose observability story is already finished, since the README lists the observable chain as coming soon. Before committing, verify three things: that your saved workflows and exported plans have been regenerated for the v3 schema and dependency graph format, that your browser or desktop bundles have been rebuilt after the pnpm reinstall, and that no API key reaches frontend code. The upgrade guide is the document to read first, not the feature list.

Frequently asked questions

Official sources

1. FellouAI/eko on GitHub
2. License: MIT
3. Project website
4. README
5. Releases