Cotor

Cotor is a local-first AI workflow runner that grew into a company-style AI operating system: a CEO AI delegates work to subordinate AIs, CLI agents keep costs down, workflows stay visible in macOS, and a goal can drive an always-on issue loop. The same Kotlin core powers pipeline execution, the localhost app-server, and the native desktop shell. Smoke test: cotor version

What Is Current In This Build

• CLI/TUI orchestration with SEQUENTIAL, PARALLEL, and DAG pipelines
• Validation, linting, status, statistics, checkpoints, and template generation
• Local web editor with YAML export and run support
• macOS desktop shell backed by cotor app-server
• Multi-company operations layer with companies, agent definitions, goals, issues, review queue, activity feed, and runtime start/stop/status
• Per-agent git branch and worktree isolation for delegated execution

Current Command Surface

Top-level commands registered in Main.kt:

init, run, dash, interactive, validate, test, template, resume, checkpoint, stats, doctor, status, list, web, app-server, lint, explain, plugin, agent, version, completion

Important entry behavior:

• cotor with no args launches interactive
• cotor tui is an alias to interactive
• unknown first args fall back to direct pipeline execution

Current subcommand support:

• agent add, agent list
• plugin init
• checkpoint gc

Current template types:

• compare
• chain
• review
• consensus
• fanout
• selfheal
• verified
• blocked-escalation
• custom

Install

Homebrew (Recommended)

brew tap bssm-oss/cotor https://github.com/bssm-oss/cotor.git
brew install cotor

This installs JDK 17 + CLI + Desktop App automatically.

Or use the one-liner:

curl -fsSL https://raw.githubusercontent.com/bssm-oss/cotor/master/shell/brew-install.sh | bash

Update:

brew upgrade cotor

From Source

git clone https://github.com/bssm-oss/cotor.git
cd cotor
./shell/cotor version   # JDK 17 auto-detected, shadowJar auto-built

Quick Start

cotor version
cotor --help
cotor init --starter-template
cotor app-server --port 8787
open "/Applications/Cotor Desktop.app"

macOS Desktop

The desktop app is included in brew install cotor. To manage separately:

cotor install    # Build + install to /Applications
cotor update     # Rebuild + reinstall
cotor delete     # Remove app

Current desktop model:

• top-level Company and TUI shell modes
• Company mode for multi-company operations, agent roster, goals, issue board/canvas, activity feed, and runtime controls
• TUI mode for repository/workspace execution with a live center terminal session
• top session strip for active execution contexts
• collapsible detail drawer for changes, files, ports, browser, and review metadata

Autonomous Company Status

The current build includes a working local operations layer:

• create multiple companies, each bound to one working folder
• define company agents with only title, CLI, and role summary
• create company goals
• decompose goals into issues
• delegate and run issues
• populate and merge ready review queue items
• inspect runtime status and recent company activity
• start and stop a local autonomous runtime loop per company

Current limits in this build:

• the app uses a Linear-style board inside Cotor; it is not a live external Linear sync
• runtime automation is intentionally minimal
• policy engine, rich follow-up generation, and full PR/CI sync are not implemented yet
• company context persistence exists as local .cotor/companies/... snapshots, but it is still a lightweight knowledge layer
• resume inspects checkpoints but does not resume execution yet

Inspect .cotor/companies/ in the working folder to review the persisted company state.

Documentation

Start here:

• Documentation Index
• Architecture Overview
• English Guide
• Korean Guide
• Quick Start
• Desktop App
• Features
• Validation Plan
• Contributing Guide
• Team Ops
• AI Agent Rules

Historical reports, release notes, and architecture drafts are linked from docs/INDEX.md under Historical / design records.

Validation

cotor version
./gradlew test