Owlyn MCP

AI agents often stop too early.

You ask an agent to work for the night. It finishes the first task in 20 minutes. Then it says "done".

Owlyn gives agents a persistent work-session clock, checkpoints, deadlines, and structured continuation decisions so they know when to keep going.

Owlyn MCP is a local-first MCP work-session supervisor for AI coding agents. It is not a simple timer, a todo app, or a background worker.

Status: v0.1.0-alpha.1 Tested with official MCP SDK stdio integration. Real host validation in progress.

Quick Start

Requirements:

• Node.js 20+

• npm

Install and build:

npm install
npm run build

Run the stdio MCP server:

node dist/index.js

Run the release checks:

npm run check

Run the manual MCP smoke test:

npm run smoke:mcp

The smoke test uses the official MCP SDK client and calls owlyn_start, owlyn_checkpoint, owlyn_should_continue, owlyn_plan_next, and owlyn_end.

Related MCP server: Taskmaster MCP Server

Example MCP Config

Generic stdio config:

{
  "mcpServers": {
    "owlyn": {
      "command": "node",
      "args": ["/absolute/path/to/owlyn-mcp/dist/index.js"],
      "env": {
        "OWLYN_DB_PATH": "/absolute/path/to/.owlyn/owlyn.sqlite"
      }
    }
  }
}

Windows example:

{
  "mcpServers": {
    "owlyn": {
      "command": "node",
      "args": ["C:\\Users\\you\\Projects\\OwlynMCP\\dist\\index.js"],
      "env": {
        "OWLYN_DB_PATH": "C:\\Users\\you\\.owlyn\\owlyn.sqlite"
      }
    }
  }
}

macOS/Linux example:

{
  "mcpServers": {
    "owlyn": {
      "command": "node",
      "args": ["/Users/you/projects/OwlynMCP/dist/index.js"],
      "env": {
        "OWLYN_DB_PATH": "/Users/you/.owlyn/owlyn.sqlite"
      }
    }
  }
}

More host examples are in docs/HOST_SETUP.md.

Agent Instruction

Copy this into your coding agent instructions when using Owlyn:

You have access to Owlyn MCP.

At the beginning of work, call owlyn_start with the user's goal and deadline.

After meaningful progress, call owlyn_checkpoint.

Then call owlyn_should_continue.

If should_continue is true, do not stop only because the current task is complete. Pick the next highest-value low-risk task and continue.

If multiple safe next tasks exist, call owlyn_plan_next.

Before final response, call owlyn_end.

Never continue destructive, irreversible, external, expensive, deployment, credential, or approval-requiring work without explicit user approval.

See docs/AGENT_INSTRUCTIONS.md for a standalone copy-paste version.

Tools

Full tool documentation is in docs/TOOLS.md.

Demo Flow

User:

Work on this repo until 06:00. If you finish early, continue with safe useful improvements.

Agent starts a session:

{
  "tool": "owlyn_start",
  "input": {
    "goal": "Improve the repo safely until morning.",
    "deadline": "06:00",
    "timezone": "Europe/Warsaw",
    "mode": "night_shift"
  }
}

Agent finishes the first task and checkpoints:

{
  "tool": "owlyn_checkpoint",
  "input": {
    "summary": "Implemented deadline parsing and added tests.",
    "completed_tasks": ["Added HH:mm deadline parsing", "Added timezone tests"],
    "next_tasks": ["Add policy tests", "Document host setup", "Run release checks"],
    "validation_results": ["npm test passed"],
    "confidence": "high",
    "risk_level": "low"
  }
}

Agent asks whether to continue:

{
  "tool": "owlyn_should_continue",
  "input": {
    "current_task_done": true,
    "has_next_tasks": true,
    "requires_user_approval": false,
    "risk_level": "low",
    "destructive_action_pending": false,
    "validation_passed": true
  }
}

Expected continuation signal:

{
  "should_continue": true,
  "reason": "The deadline has not been reached and safe next tasks are available.",
  "recommended_action": "Continue with the next highest-value low-risk task. Do not stop only because the current task is complete."
}

Longer example: docs/EXAMPLE_SESSION.md.

What Owlyn Stores

Owlyn is local-first and persists session state in SQLite.

Default database path:

~/.owlyn/owlyn.sqlite

Override it with:

OWLYN_DB_PATH=/custom/path/owlyn.sqlite

Owlyn stores only what the agent sends to it:

• session goals

• notes

• checkpoints

• task lists

• file-change notes

• validation notes

• continuation decisions

Do not store secrets in goals, notes, checkpoints, task descriptions, or validation output.

Safety and Limitations

Owlyn MCP is intentionally conservative.

It should stop when work requires user approval, when destructive action is pending, when the deadline is reached, or when risk is high.

Owlyn v0.1 has:

• local-first SQLite persistence

• stdio MCP transport

• no cloud

• no telemetry

• no auth

• no browser extension

• no dashboard

• no background autonomous worker

• no shell execution by the server

• no project-file modification by the server

Owlyn MCP does not keep your agent alive by itself. It provides session state and continuation policy through MCP tools. Your host agent must call the tools and follow Owlyn's policy.

Host behavior still depends on the MCP client, model, agent instructions, context limits, tool-call limits, user approval gates, rate limits, and runtime timeouts.

Troubleshooting

better-sqlite3 native dependency issues: Make sure Node.js and npm are installed normally for your platform. If installation fails, check that your Node version is supported and that your environment can install native npm packages.

Node version requirement: Owlyn requires Node.js 20 or newer. Check with node --version.

OWLYN_DB_PATH usage: Set OWLYN_DB_PATH when you want Owlyn to store its SQLite database somewhere other than ~/.owlyn/owlyn.sqlite. The parent directory is created automatically.

No active session found: Call owlyn_start first, or pass a known session_id to tools that support it. Completed or abandoned sessions are not treated as the latest active session.

Invalid deadline format: Use ISO datetime or HH:mm, for example 2026-07-07T06:00:00+02:00, 2026-07-07T06:00:00, or 06:00.

Roadmap

Future ideas:

• optional JSON/Markdown export

• optional session templates

• optional host-specific config helpers

• optional durable workflow integration

• optional UI dashboard

• optional per-project session profiles

• optional MCP resources for reports

• optional pause/resume

• optional session budget limits

• optional multi-agent coordination

These are not implemented in v0.1.

Development

npm install
npm run typecheck
npm run build
npm test
npm run smoke:mcp
npm run check

Release checklist: RELEASE_CHECKLIST.md.

License

MIT