Rowan Agent

A composable, self-evolving agent loop for agentic workflows.

Rowan replaces opaque prompt loops with explicit, controllable workflows — structured phases that improve over time.

Key Principles:

• Composable, programmable loop: Standardizes agent loop into structured phases like research, planning, verification — each defined by executable code or prompt, no more hallucination.
• Self-improving workflow: Phases are composable, reusable, and evolvable — runtime feedback iterates on them over time.
• Extensible by design: Add custom phases, tools, skills, and providers without touching the core runtime.

See details in docs/phases, docs/extensions.

Quick Start

Clone the repository and install dependencies:

git clone https://github.com/aiirobyte/rowan-agent.git
cd rowan-agent
bun install

Run a one-shot prompt with explicit model flags:

bun run rowan \
  --model gpt-4.1-mini \
  --api-key "$OPENAI_API_KEY" \
  "list the files in this directory"

For repeat use, copy the example multi-provider config into .rowan/config.yaml:

mkdir -p .rowan
cp examples/config.yaml .rowan/config.yaml

What is Rowan Agent?

The core idea is Loop Engineering: the agent loop is treated as reusable product code. Each run has a context, tools, phases, durable session, structured events, and a terminal outcome. As those pieces improve, the agent's process improves by building your own phase.

Architecture

rowan-agent/
├── packages/
│   ├── models/    # Model registry, provider dispatch, SSE streaming, cost calculation
│   ├── agent/     # Core runtime: phase loop, tools, skills, sessions, extensions
│   ├── logging/   # AgentEvent loggers with secret redaction
│   └── cli/       # Command-line interface
├── examples/      # Config, phase, and extension examples
└── package.json

@rowan-agent/cli
    ├── @rowan-agent/agent
    │       └── @rowan-agent/models
    ├── @rowan-agent/models
    └── @rowan-agent/logging
            └── @rowan-agent/models

CLI & Configuration Examples

bun run rowan "what files are in this directory?"
bun run rowan --model gpt-4.1-mini "use a different model"
bun run rowan config                # print resolved config (secrets redacted)

Model configuration lives at <workspace>/.rowan/config.yaml:

cp examples/config.yaml .rowan/config.yaml

Development

bun run build           # Type-check all packages
bun run build:packages  # Build distributable packages
bun test                # Run all tests
bun test packages/agent # Run tests for a specific package

Release scripts:

bun run build:packages
bun run publish:packages
bun run release

Documentation

Doc	Description
Agent package README	Core runtime API, tools, events, sessions, phases, extensions, config
Models package README	Model registry, providers, streaming, protocol types
Logging package README	Console and Pino event loggers
CLI package README	CLI usage, options, sessions, output behavior
Examples	Config templates, extension examples, phase examples
Phases	PHASE.md format, routing, execution modes, parallel phases
Extensions	Extension discovery, hooks, tools, phases, providers, event bus

Acknowledgements

Inspired by pi-agent-core and Cahciua.

License

MIT - see LICENSE for details.