Eldwin

Agent runtime for memory-driven action.

Pensieve remembers. Eldwin acts.

Eldwin helps Codex, Claude Code, Cursor, and other coding agents turn a plain-language request into a runnable agent capability package. You describe the job. The coding agent creates the tools, skills, workflows, commands, tests, and README needed to try it locally.

Eldwin is not meant to make users learn a framework before the first result. It is meant to give agent-built capabilities a clean package shape, a portable runtime surface, and enough policy to move across clients without rewriting the business logic.

Start Here

Open this repository in Codex, Claude Code, Cursor, or another coding agent and paste:

Create an agent for this job:

<describe the task I want the agent to do>

Use Eldwin. Generate the extension or product package, tools, skills,
workflows, tests, README, and run command. Keep it simple enough that I can try
it locally right away.

The agent should read the project instructions, follow docs/ai-agent-builder.md, and create a small package under extensions/ unless your request clearly needs a full product command.

What Eldwin Builds

An Eldwin package can contain:

• Tools for MCP-callable actions, CLI wrappers, API reads, scripts, or service operations.
• Skills that teach the agent a repeatable procedure.
• Workflows that make multi-step work deterministic, resumable, and inspectable.
• Commands that give users a direct entry point.
• Agents for specialized roles that can be projected into supported clients.
• Tests and package metadata so the generated capability can be validated without depending on a single agent client.

The same capability package can be projected into Codex, Claude Code, Cursor, MCP clients, OpenAI Agents SDK, and other harnesses.

The Mental Model

Eldwin keeps business logic in portable package resources and keeps client adapters thin.

plain-language task
        |
        v
coding agent follows docs/ai-agent-builder.md
        |
        v
extensions/<capability>/
  tools/      skills/      workflows/
  commands/   agents/      test/
        |
        v
Eldwin runtime loads package resources
        |
        v
MCP tools, workflow runner tools, and client-native profiles

Extension packages own reusable capabilities. Product packages combine one or more capabilities into a runnable command when the user needs a packaged agent experience.

Architecture

Extension packages own the actual capabilities. The framework loads that shared inventory, applies runtime policy, exposes MCP tools, and lets thin adapters project the same resources into different agent clients.

Key runtime files:

• src/extensions/packageRegistry.ts discovers extension and product packages.
• src/extensions/localToolLoader.ts loads command-backed and module-backed tools.
• src/extensions/workflowRunner.ts persists workflow runs and executes one ordered step at a time.
• src/mcp-server.ts exposes extension tools plus workflow runner tools over MCP.
• src/client-profile-cli.ts generates client-native startup files.
• scripts/package-self-test.mjs validates generated package contracts.

For deeper architecture details, read docs/runtime-architecture.md.

Build And Test

Install Eldwin from npm:

npm install @eldwin-ai/eldwin

Install dependencies and build the framework:

npm install
npm run build

Run the unit test suite:

npm test

Validate an extension or product package from its package directory:

npm exec -- eldwin-package-test

Check GitHub governance files for the main repo and extension repos:

npm run github:check

Try the included smoke extension:

npm run build
(cd extensions/codex-smoke && npm install && npm exec -- eldwin-package-test)

Run The MCP Server

After building, start the MCP server from the framework or product checkout:

node dist/mcp-server.js

The server exposes package tools plus deterministic workflow runner tools:

• eldwin_list_workflows
• eldwin_describe_workflow
• eldwin_start_workflow
• eldwin_get_workflow_run
• eldwin_run_next_step

Workflow runs are persisted under .eldwin-runtime/workflow-runs/. Each eldwin_run_next_step call executes exactly one pending step, so clients can inspect progress, stop for approval, and resume without asking the model to remember what happened earlier.

Generate Client Profiles

Generate client-native profile files from shared Eldwin resources:

npm exec -- eldwin-client-profile -- --client all

This can project resources into:

• Codex: .codex/config.toml, .codex/agents/, .agents/skills/, and .codex/prompts/.
• Claude Code: .claude/settings.json, .claude/agents/, and .claude/commands/.
• Cursor: .cursor/rules/eldwin-runtime.mdc.

Inspect Extension Catalog

Print a machine-readable catalog of discovered extensions, resource counts, validation commands, and builder-loop readiness:

node dist/extension-catalog-cli.js

Use this before and after creating an extension to see which packages are ready for the builder loop and which still need README, entrypoint, runtime resource, or local test coverage. Installed packages also expose this as eldwin-extension-catalog.

Create Extension Scaffold

Generate a minimal extension package with README, package contract, skill, slash command, and discovery test:

node dist/extension-builder-cli.js create-extension --name github-triage

After adding package-specific tools or workflows, rerun the catalog command to confirm the new extension is builder-ready.

Live Codex Workflow Test

Run the model-backed Codex end-to-end workflow test locally:

npm run test:e2e:codex

This launches real Codex, asks the model to use the Eldwin MCP workflow runner, and asserts from the JSONL event stream that the model listed workflows, started codex-smoke:codex-smoke, executed each next step, and reached completed.

This test is intentionally not part of default CI because it uses live model quota and local Codex authentication.

Documentation Map

• docs/ai-agent-builder.md: recipe for turning a user task into a complete Eldwin package.
• docs/extension-package.md: package layout, manifest fields, and resource examples.
• docs/runtime-architecture.md: runtime model, adapter boundaries, package loading, policy, and traces.
• docs/runtime-extension-patterns.md: ownership rules for tools, skills, agents, workflows, products, and adapters.
• docs/github-setup.md: GitHub files, secrets, repo settings, and extension repo synchronization.
• docs/tool-capability-review.md: classification guide for integration, atomic helper, draft-only, knowledge, and internal tools.
• docs/tool-atomic-helper-review.md: labels for shrinking broad tools back to deterministic helpers.
• docs/runtime-boundary-catalog.yaml: machine-readable runtime boundary catalog.
• docs/prompt-asset-catalog.yaml: prompt asset organization rules for short skills and split runbooks.

Included Example

extensions/codex-smoke/ is the smallest useful Eldwin package shape for a Codex client. It includes:

• MCP tool: codex_smoke_status
• Skill: codex-smoke
• Slash command: /codex-smoke
• Sub-agent: codex-smoke-agent
• Workflow: codex-smoke

After the framework is built, you can ask an Eldwin-aware client:

List Eldwin workflows, start codex-smoke:codex-smoke, and run each next step
until it completes.