deckent

The AI orchestrator for developers who want discipline.

Deckent is an AI agent orchestration CLI with two modes: Sprint Mode for structured multi-agent development sprints, and Task Mode for one-shot life assistant tasks. Write your goals, and Deckent plans tasks, assigns parallel AI workers, monitors quality, and delivers results — all with discipline.

AST-sandboxed skills • Nervous System • Memory V2 (SQLite FTS5) • 3 backends • 3 providers • cross-platform

Quick Start

npm install -g deckent

# Developer workflow (Sprint Mode)
deckent init
deckent mode sprint
# Edit DIRECTIVES.md with your goals, then:
deckent start

# Life assistant (Task Mode)
deckent mode task
deckent run "Remind me to review the PR before end of day"

Dual Mode: Sprint + Task

Deckent operates in two distinct modes, switchable with a single command:

Mode	Command	Use Case
Sprint	`deckent mode sprint`	Structured multi-agent development: PLAN→SPAWN→EXECUTE→EVALUATE→RETRO
Task	`deckent mode task`	One-shot life assistant: single task, immediate execution, no sprint overhead

deckent mode show      # Show current mode
deckent mode sprint    # Switch to sprint mode (developer workflow)
deckent mode task      # Switch to task mode (life assistant)
deckent mode auto      # Auto-detect from context (git + DIRECTIVES.md → sprint)
deckent mode global task  # Set global default

The deckent_style config key persists your choice across sessions. Task Mode brings a full life-assistant experience — one-shot tasks, idle detection, and connector notifications.

How It Works

Sprint Mode

                    DIRECTIVES.md
                         |
                    [ Brain: Plan ]
                    /    |    \
              Worker1  Worker2  Worker3   (parallel, scoped)
                    \    |    /
                    [ Brain: Evaluate ]
                         |
                  GO / NO-GO / TECH_DEBT

Describe — Write goals in DIRECTIVES.md
Plan — Brain reads goals, creates scoped prioritized tasks
Execute — Parallel AI workers build, test, and report results
Evaluate — Every task gets GO / NO-GO / TECH_DEBT verdict

Task Mode

  User Input → [ Task Runner ] → Worker → Result

Single-task execution. No PLAN/SPAWN phases. Ideal for quick commands, reminders, and life-assistant use cases.

Architecture

+------------------------------------------------------------------+
|                         deckent CLI                               |
+------------------------------------------------------------------+
|                                                                  |
|   +----------+     +----------+     +----------+                 |
|   |  Brain   |---->| Worker 1 |     | Auditor  |                 |
|   | (plans,  |---->| Worker 2 |     | (scans,  |                 |
|   | evaluates|---->| Worker N |     |  alerts) |                 |
|   +----------+     +----------+     +----------+                 |
|        |                                   |                     |
|   .brain/            .tasks/          .dashboard                 |
|   (memory DB,        (task JSON,      (live status)              |
|    decisions,         results,                                   |
|    patterns)          heartbeats)                                |
+------------------------------------------------------------------+
|         Nervous System — Proactive Meta-Orchestrator             |
+------------------------------------------------------------------+

Brain — Plans tasks, assigns models, evaluates results, learns across sprints
Workers — Execute tasks in parallel (tmux, subprocess, or Docker), each with plan-code-test-report cycle
Auditor — Monitors heartbeats, detects boundary violations, enforces quality
Nervous System — Proactive meta-orchestrator: detects anomalies, idle states, routing patterns, and emits contextual notifications

Key Features

Core Orchestration

Sprint Lifecycle — 8-phase structured cycle: PLAN, SPAWN, EXECUTE, EVALUATE, FIX, RETRO, DECAY, CLEANUP
Dual Mode — deckent_style: 'sprint' | 'task' — developer orchestration or one-shot life assistant
Multi-Worker Parallel Execution — Up to 10 AI workers simultaneously, each in isolated scope
GO / NO-GO Evaluation — Every task result evaluated against defined criteria; NO-GO tasks logged and optionally retried
Auditor Quality Gate — Stale heartbeat detection, boundary violation scanning, deadlock detection via Kahn's algorithm

Security & Safety

AST Sandbox — All skills run through AST validation before execution. No arbitrary code injection. Compared to OpenClaw's 13K+ skill hub with ~20% flagged as malicious, Deckent's sandbox validates every skill before it runs
Scope Enforcement — Workers may only touch files in their assigned scope.filesWrite — Auditor enforces this via git diff --stat
RBAC Protocol — ADR-037 Brain-Auditor-Worker authority matrix; strict role boundaries
.deck Secret Interpolation — Reference secrets in config as $DECK:MY_TOKEN — secrets loaded from encrypted .deck file at runtime, never committed

Intelligence & Memory

Nervous System — Proactive meta-orchestrator (ADR-040): idle detection, routing anomaly alerts, agent health monitoring, contextual notifications
Memory V2 DB-First — SQLite + FTS5 full-text search, dual-layer Turkish/English normalize, 96% context reduction vs raw markdown. deckent recall "docker heartbeat" finds relevant ADRs and sprint learnings instantly
Brain Auto-Query — Task DNA → relevant ADRs/patterns/learnings auto-queried at PLAN, SPAWN, EVALUATE phases
Self-Learning — Brain generates config suggestions from sprint results (NO_GO rate, coverage, duration)

Agents & Skills

15 Built-in Agents — security-auditor, doc-writer, bug-fixer, code-reviewer, refactorer, api-builder, performance-analyzer, ci-guardian, architect, architecture-planner, accessibility-auditor, data-engineer, devops-engineer, frontend-designer, migration-specialist
21 Built-in Skills — typescript-expert, testing-expert, react-specialist, security-specialist, docker-expert, and 16 more
Temp Agent & Skill Generation — Auto-generates project-specific agents and skills from your codebase conventions
Agent Evolution Pipeline — Promotion from temp to permanent based on performance; demotion on failure

Infrastructure

3 Backends — tmux (Linux/macOS), subprocess (all platforms including native Windows), Docker (isolated containers)
3 Providers — Claude (default), OpenAI Codex, Google Gemini — 13 models, 4 tiers
Tier-Based Routing — brain_tier: 'premium' instead of model names; ModelRegistry resolves best model per provider
Configurable Timeouts — Per-task and per-sprint timeout, sprint_timeout_minutes: 0 for unlimited
Human Checkpoints — Configurable approval gates at plan, evaluate, fix phases
MCP Integration — 31 tools + 8 resources for Claude Code IDE integration
Web Dashboard — React + Vite + Tailwind, 6 pages, SSE real-time updates, TR/EN language switcher

Cross-Platform

Linux — Full (Ubuntu 20+, Debian 11+, Fedora 38+, Arch)
macOS — Full (12+)
Windows WSL2 — Full (recommended for tmux workflows)
Native Windows — Full (subprocess backend, shell:true, UTF-8 support)

Comparison

April 2026 — see full competitive analysis for detailed head-to-head breakdowns.

Feature	deckent	Cursor Agents	Devin	OpenClaw	Claude Code
Sprint lifecycle (8-phase)	Yes	No	Partial	No	No
Multi-agent parallel execution	Yes (10 workers)	Limited	Yes	Yes (100+ AgentSkill)	No
Automatic task planning from goals	Yes (AI + structured)	No	Yes	No	No
AST sandbox for skills	Yes	No	No	No	No
Quality auditor with boundary enforcement	Yes	No	No	No	No
Nervous System (proactive meta-orchestrator)	Yes	No	No	No	No
Memory V2 (SQLite FTS5, cross-sprint learning)	Yes	No	No	3rd party	No
Dual mode (sprint + task)	Yes	No	No	No	No
`.deck` secret interpolation	Yes	No	No	No	No
GO/NO-GO evaluation per task	Yes	No	No	No	No
Open source	Yes (MIT)	No	No	Yes (OSS)	No
MCP integration	Yes (31 tools, 8 resources)	Partial	No	Limited	Native
Web dashboard	Yes (6 pages)	Built-in	Built-in	No	No
Multi-provider (Claude, Codex, Gemini)	Yes	No	No	Limited	No
Built-in agents	15	—	—	100+	—
Built-in skills	21	—	—	13K+ (hub, ~20% flagged)	—
Test coverage	89.33%	—	—	—	—
Price	Free (MIT)	$20-40/mo	$20-500/mo	Free	Free

Requirements

Requirement	Version	Check
Node.js	>= 20	`node --version`
git	any	`git --version`
Claude Code CLI	any	`claude --version`
tmux	any (optional, Linux/macOS)	`tmux -V`
OpenAI Codex CLI	any (optional)	`codex --version`
Google Gemini API	any (optional)	`GOOGLE_API_KEY` env var

Claude Subscription: Pro, Max 5x, Max 20x, or API key (pay-as-you-go). Other providers (Codex, Gemini) require their respective API keys.

Installation

npm install -g deckent

Verify:

deckent --version    # 1.0.0-beta.1
deckent doctor

CLI Usage

Initialize a Project

cd my-project
deckent init

  Welcome to Deckent!

  ? Select your plan:
    > Performance -- 8 workers, premium model brain
      Balanced    -- 5 workers, standard model brain
      Economic    -- 3 workers, standard model only
      API (pay-as-you-go) -- 10 workers, any model

  Detected stack: TypeScript + Vitest + React
  ? Project name: my-project

  Next: Edit DIRECTIVES.md with your first goals, then run `deckent start`

Set Your Mode

deckent mode sprint   # Developer orchestration (default)
deckent mode task     # Life assistant (one-shot tasks)
deckent mode auto     # Auto-detect from context

Start a Sprint (Sprint Mode)

# Edit DIRECTIVES.md with your goals, then:
deckent start

# Preview plan without executing:
deckent start --dry-run

# Auto-approve all worker tool permissions:
deckent start --auto-approve

Run a One-Shot Task (Task Mode)

deckent mode task
deckent run "Organize my downloads folder by file type"
deckent run "Draft a reply to the GitHub issue about memory leaks"

Check Status

deckent status
deckent status --watch   # Auto-refresh every 2s
deckent status --json    # Machine-readable output

Sprint sprint-149 -- EXECUTE phase

  TASK        STATUS      MODEL    LAST HEARTBEAT
  149-001     EXECUTING   sonnet   5s ago
  149-002     DONE        haiku    42s ago

Progress: 1/2 done  |  0 failed  |  1 running

Query Memory

deckent recall "docker heartbeat"         # Cross-source FTS5 search
deckent recall "ADR-037 RBAC"             # Find architecture decisions
deckent remember "Deploy freeze until Friday"  # Save a note
deckent memory stats                       # Memory DB stats
deckent memory export                      # Export DB → .md snapshots

Health Check

deckent doctor

  node_version   v20.11.0 (>=20 required)     [pass]
  git            git 2.43.0                    [pass]
  tmux           tmux 3.3a                     [pass]
  claude_cli     claude 1.2.3                  [pass]
  workspace      .deckent/ found               [pass]

All Commands

Command	Description
`deckent init`	Interactive setup wizard
`deckent mode [show\|sprint\|task\|auto\|global]`	Get/set runtime mode
`deckent start`	Run the full sprint lifecycle
`deckent plan`	Plan the next sprint (plan mode only)
`deckent status`	Show live dashboard
`deckent run <cmd>`	Run a task (one-shot in task mode, queued in sprint mode)
`deckent attach`	Attach to the tmux session
`deckent spawn <id>`	Manually spawn a worker
`deckent kill <id>`	Kill a specific worker
`deckent retro`	Read sprint retrospective
`deckent cleanup`	Archive sprint files and kill workers
`deckent doctor`	Check system health
`deckent audit <sprint-id>`	Run Brain Self-Audit Gate for a sprint
`deckent recover <sprint-id>`	Recover a crashed or incomplete sprint
`deckent config`	Show/edit configuration
`deckent config set <key> <value>`	Set a config value
`deckent history`	Show sprint history and metrics
`deckent analyze`	Analyze project stack and size
`deckent dashboard`	Terminal TUI dashboard
`deckent serve`	Start HTTP API server
`deckent web`	Web dashboard + API server (localhost:3100)
`deckent recall <query>`	Search project memory (ADRs, learnings, debt)
`deckent remember <note>`	Save a note to memory
`deckent memory [rebuild\|export\|stats]`	Memory DB management
`deckent skill`	List or manage installed skills
`deckent skill publish <path>`	Publish a skill to DeckentHub (Ed25519 signed)
`deckent features [--category]`	List feature manifest (active\|dormant\|dead\|all)
`deckent agent`	Manage agent pool (list, inspect, reset)
`deckent review`	Review last sprint results
`deckent upgrade`	Self-update (`--local <path.tgz>` for beta installs)
`deckent sync`	Sync adapter files with DECKENT.md
`deckent explain <topic>`	Explain a concept or command
`deckent heartbeat`	One-shot heartbeat check (`--daemon` for background)
`deckent checkpoint`	Approve/reject human checkpoints

MCP Integration

Deckent integrates with Claude Code via the Model Context Protocol:

claude mcp add deckent -- npx deckent mcp

Or let deckent init auto-register it.

MCP Tools (22)

Tool	Description
`deckent_init`	Initialize project structure
`deckent_set_directives`	Write sprint goals to DIRECTIVES.md
`deckent_plan`	Preview the sprint plan
`deckent_start`	Start a sprint in the background
`deckent_status`	Get current sprint status
`deckent_doctor`	Run health checks
`deckent_retro`	Read last retrospective
`deckent_history`	View sprint history
`deckent_analyze_project`	Analyze project stack
`deckent_sync`	Sync adapter files
`deckent_config`	Show or update configuration
`deckent_review`	Review last sprint results
`deckent_run`	Run an arbitrary command in project context
`deckent_kill`	Kill a specific worker
`deckent_cleanup`	Archive sprint files and clean up workers
`deckent_help`	Runtime capabilities, state info, and workflow guidance
`deckent_agent_list`	List registered agents (built-in and temporary)
`deckent_skill_list`	List registered skills with manifest info
`deckent_checkpoint`	Approve/reject human checkpoints
`deckent_docs`	Manage and serve built-in documentation
`deckent_explain`	Explain sprint history and results
`deckent_memory_query`	Cross-source memory search (ADR, sprint, debt, pattern)

MCP Resources (8)

Resource URI	Contents
`deckent://dashboard`	Live sprint dashboard
`deckent://directives`	Current DIRECTIVES.md
`deckent://memory`	Learned patterns from past sprints
`deckent://debt`	Technical debt items
`deckent://config`	Project configuration
`deckent://retro`	Last sprint retrospective
`deckent://tasks`	Active task list and statuses
`deckent://agents`	Agent pool and performance stats

Configuration

Configuration lives in .deckent/config.json (project) and ~/.deckent/config.json (global). Project config overrides global.

Key Options

Option	Type	Default	Description
`deckent_style`	string	`"sprint"`	Runtime mode: `sprint` (developer) or `task` (life assistant)
`mode`	string	`"performance"`	Plan tier: `performance`, `balanced`, `economic`, `api`
`language`	string	`"en"`	Output language: `en`, `tr`
`brain_planning`	string	`"auto"`	Planning mode: `ai`, `structured`, `auto`
`brain_provider`	string	`"claude"`	Provider for Brain: `claude`, `codex`, `gemini`
`worker_provider`	string	`"claude"`	Provider for workers: `claude`, `codex`, `gemini`
`fallback_provider`	string	—	Fallback provider on failure
`spawn_backend`	string	`"tmux"`	Worker backend: `tmux`, `subprocess`, `docker`
`sprint_timeout_minutes`	number	`60`	Hard sprint timeout; `0` for unlimited

Plan Tiers

Tier	Max Workers	Brain Model	Default Model
`performance`	8	opus	opus
`balanced`	5	sonnet	opus
`economic`	3	sonnet	sonnet
`api`	10	opus	sonnet

Multi-Provider Support

Provider	Models	Env Var
Claude (default)	opus, sonnet, haiku	Session auth or `ANTHROPIC_API_KEY`
Codex (OpenAI)	o3, gpt-5, gpt-4.1, o4-mini, gpt-5-mini, gpt-4.1-mini	`OPENAI_API_KEY`
Gemini (Google)	gemini-3.1-pro-preview, gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash	`GOOGLE_API_KEY`

13 models across 3 providers. Tier equivalence: premium_plus (o3, gemini-3.1-pro-preview), premium (opus, gpt-5, gemini-2.5-pro), standard (sonnet, gpt-4.1, o4-mini, gemini-2.5-flash), economy (haiku, gpt-5-mini, gpt-4.1-mini, gemini-2.0-flash).

See docs/reference/multi-provider.md for the full guide.

`.deck` Secret Interpolation

Reference secrets in your config without committing them:

{
  "connectors": {
    "discord": { "enabled": true, "token": "$DECK:DISCORD_TOKEN" },
    "telegram": { "enabled": true, "token": "$DECK:TELEGRAM_TOKEN" }
  }
}

Secrets are loaded from the .deck file at runtime. The .deck file is gitignored by default.

See docs/reference/config-reference.md for the full reference.

Docker Backend (Isolated Workers)

Workers run in isolated Docker containers — no cross-worker file conflicts.

docker build -f Dockerfile -t deckent-worker:latest .
npx deckent config set spawn_backend docker

Project mounted read-only (/workspace)
.tasks/ mounted read-write (results, heartbeats)
Non-root execution (deckent user)
Configurable timeout: npx deckent config set docker_timeout 1800 (default: 1200s)

See docs/guide/docker-backend.md for the full guide.

Nervous System

The Nervous System is a proactive meta-orchestrator that runs alongside sprints:

Screenshot coming in Sprint 151 — deckent nervous for live TUI

Detectors — Pluggable detectors for stale tasks, idle state (task mode), routing anomalies, agent health
Notifications — Contextual alerts via event bus; Discord/Telegram connectors in Sprint 149+
Task Mode Idle — In task mode, notifies after 5 minutes of inactivity
Proactive — No polling required; detectors run on cron events and sprint lifecycle events

Web Dashboard

deckent web   # Opens at localhost:3100

React + Vite + Tailwind — 6 pages (Dashboard, Settings, History, Memory, Config, Status), SSE real-time updates, dark/light theme, TR/EN language switcher.

Full screenshot gallery coming in Sprint 151

Workspace Structure

After deckent init:

my-project/
  DECKENT.md              # Single source of truth (agent config)
  DIRECTIVES.md           # Your goals — edit before each sprint
  CLAUDE.md               # Claude Code adapter
  AGENTS.md               # Generic agent adapter
  .deckent/
    config.json           # Runtime config (deckent_style, mode, providers)
    workspace/            # Identity, tools, boot sequence
    docs/                 # Built-in guides (quick-start, directives, config)
    agents/               # Agent pool (built-in + temp agents, LRU eviction)
    skills/               # Skill registry (built-in + temp skills, AST validated)
    plugins/              # Installed plugins
    i18n/                 # Language files (en, tr)
  .brain/
    memory.db             # SQLite DB — single source of truth (gitignored)
    exports/
      summary.md          # Auto-generated context summary (git-tracked)
      decisions.md        # ADR list (git-tracked)
      memory.md           # Sprint learnings (git-tracked)
      debt.md             # Technical debt (git-tracked)
    archive/              # Per-sprint logs
  .tasks/                 # Task JSON files (managed by Brain)
  .locks/                 # File locks (managed by workers)
  .deck                   # Secret file (gitignored — $DECK:KEY references)

Crash Recovery

Deckent knows how to recover itself — and gives you the tools to recover too.

# Run Brain Self-Audit Gate for any past sprint
deckent audit sprint-150

# Recover a crashed or incomplete sprint (interactive, confirms before destructive ops)
deckent recover sprint-150 --dry-run   # preview what would be cleaned
deckent recover sprint-150             # execute recovery

Gate: PASS
tsc: pass, vitest: pass
Written: .deckent/sprint-150-gate.json

If a sprint crashes mid-execution (network cut, OOM, coordinator panic), deckent recover runs audit + orphan cleanup + stale lock clear + task archive in one command.

DeckentHub — Skill Registry

DeckentHub is a curated skill registry where every skill is:

AST-sandboxed — Validated before execution, no arbitrary code injection
Ed25519-signed — Cryptographically signed by the author
CI-validated — GitHub Actions validates sandbox + signature on every PR

deckent skill publish ./my-skill   # Sign + submit to DeckentHub

The hub launches with 20 seed skills in Sprint 150: spotify-control, telegram-bot, discord-moderator, calendar-google, and 16 more.

Contributing

See CONTRIBUTING.md for development setup, testing guide, code standards, and PR process.

Documentation

License

MIT — Alperen @ Verhex

GitHub: github.com/VerhexIO/deckent Website: deckent.agency

Name		Name	Last commit message	Last commit date
.brain		.brain
.claude		.claude
.codex/rules		.codex/rules
.contracts		.contracts
.deckent		.deckent
.gemini/rules		.gemini/rules
.github		.github
deckent-hub		deckent-hub
docs		docs
examples/quickstart		examples/quickstart
scripts		scripts
src		src
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
.pre-commit-config.yaml		.pre-commit-config.yaml
.secrets.baseline		.secrets.baseline
AGENTS.md		AGENTS.md
BETA-TRACKER-TR.md		BETA-TRACKER-TR.md
BETA-TRACKER.md		BETA-TRACKER.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
COMPETITIVE-ANALYSIS.md		COMPETITIVE-ANALYSIS.md
CONTRIBUTING.md		CONTRIBUTING.md
DECKENT-ANA-PLAN-TR.md		DECKENT-ANA-PLAN-TR.md
DECKENT-MASTER-BLUEPRINT.md		DECKENT-MASTER-BLUEPRINT.md
DECKENT-TEST-REPORT.md		DECKENT-TEST-REPORT.md
DECKENT.md		DECKENT.md
DIRECTIVES.md		DIRECTIVES.md
Dockerfile		Dockerfile
Dockerfile.worker		Dockerfile.worker
LICENSE		LICENSE
NEXT-SESSION-PROMPT.md		NEXT-SESSION-PROMPT.md
README-TR.md		README-TR.md
README.md		README.md
SECURITY.md		SECURITY.md
SYSTEM-MIGRATION-2026-04-22.md		SYSTEM-MIGRATION-2026-04-22.md
VISION-TR.md		VISION-TR.md
VISION.md		VISION.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
vitest.dashboard.config.ts		vitest.dashboard.config.ts

Latest commit

History

Folders and files

Repository files navigation

deckent

Quick Start

Dual Mode: Sprint + Task

How It Works

Sprint Mode

Task Mode

Architecture

Key Features

Core Orchestration

Security & Safety

Intelligence & Memory

Agents & Skills

Infrastructure

Cross-Platform

Comparison

Requirements

Installation

CLI Usage

Initialize a Project

Set Your Mode

Start a Sprint (Sprint Mode)

Run a One-Shot Task (Task Mode)

Check Status

Query Memory

Health Check

All Commands

MCP Integration

MCP Tools (22)

MCP Resources (8)

Configuration

Key Options

Plan Tiers

Multi-Provider Support

.deck Secret Interpolation

Docker Backend (Isolated Workers)

Nervous System

Web Dashboard

Workspace Structure

Crash Recovery

DeckentHub — Skill Registry

Contributing

Documentation

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`.deck` Secret Interpolation