A development workflow orchestration platform that creates collaborative environments for both human and AI developers through organizational cybernetic principles.
"The power of intelligence stems from our vast diversity, not from any single, perfect principle." — Marvin Minsky, The Society of Mind
Coordinate work items across different storage systems:
# Minsky database (default)
minsky init --tasks-backend minsky
# GitHub Issues for open source projects
minsky init --tasks-backend github-issuesIsolated workspaces that prevent conflicts and enable parallel work:
# Start an isolated session for a task
minsky session start --task mt#123
# Work in the isolated environment
cd $(minsky session dir mt#123)
# Create a PR when ready
minsky session pr create --title "Fix critical bug" --type fixMinsky exposes all commands as both CLI and MCP tools, so AI agents interact with the same interface as human developers. There is no separate AI API — the same session start, tasks create, and session pr create commands work whether you are typing them in a terminal or an agent is calling them via MCP.
Tools like CodeRabbit, GitHub Copilot Review, and Greptile operate at PR time — they review code after it is written. Minsky audits the development environment: the hooks, gates, and workflows that shape how code gets written in the first place. By the time code reaches a PR, Minsky's quality gates have already run many times.
Minsky is the coordination layer that makes your existing tools work as a coherent system. Your linter, test runner, and CI pipeline already exist — Minsky configures them to run at the right moments and surfaces their results in a consistent format. It does not replace them.
The core design principle: the same pre-commit hook that blocks a human developer from committing unformatted code blocks an AI agent too. No special AI configuration is needed. The environment enforces the constraints uniformly.
This is the difference between instruction-based alignment ("tell the AI to write clean code") and environmental alignment ("make unformatted code impossible to commit"). Minsky implements the latter.
Minsky runs on your infrastructure, in your git repository. It integrates with Anthropic, OpenAI, and Google models via the Vercel AI SDK (@ai-sdk/anthropic, @ai-sdk/openai, @ai-sdk/google) — you choose the provider. This contrasts with hosted agent platforms (e.g., Claude Managed Agents) which are cloud-only, single-provider, and designed for async business tasks rather than development workflows.
Sessions are isolated git clones. Changesets are branches. Pull requests are the integration mechanism. There is no proprietary state format — everything lives in git and is inspectable with standard tools.
# Clone repository
git clone https://github.com/edobry/minsky.git
cd minsky
# Install with Bun (recommended)
bun install
bun link
# Or with npm
npm install
npm link# Interactive setup — configures task backend and git hooks
minsky init# Create a task
minsky tasks create --title "Add user authentication"
# Start a session
minsky session start --task mt#1
# Work in the isolated environment
cd $(minsky session dir mt#1)
# Make changes, then create a PR
minsky session pr create --title "feat: Add user authentication"minsky ships tab-completion for bash, zsh, and fish via @pnpm/tabtab. One-time setup:
# Interactive: prompts for which shell to set up
minsky completions install
# Then re-source your shell config (or open a new shell)
exec $SHELL -lAfter install, tab-complete top-level commands, subcommands, option flags, AND option values:
minsky <TAB> # → tasks, session, rules, git, config, mcp, ...
minsky tasks <TAB> # → list, get, create, status, ...
minsky tasks list --<TAB> # → --backend, --status, --tag, ...
minsky tasks list --status <TAB> # → TODO, PLANNING, READY, IN-PROGRESS, ...
minsky git merge --conflict-strategy <TAB> # → automatic, guided, manual
Value completion (--status <TAB> → enum values) is automatic for any option whose underlying Zod schema in the shared command registry is a finite enum (z.enum([...]), z.union([z.literal(...), ...]), or any of those wrapped in .optional() / .default(...) / .nullable()). Free-form options (z.string(), z.number()) produce no values — those fall through to the shell's default behavior.
To uninstall, run minsky completions uninstall. For manual install (bypassing the interactive prompt), minsky completions bash, minsky completions zsh, or minsky completions fish emit the raw completion script to stdout — pipe it into the appropriate shell config.
Dynamic value completion (tasks get <TAB> → live task IDs queried from the DB at TAB time) is tracked separately as mt#1894. Windows and PowerShell are not supported.
Minsky applies principles from organizational cybernetics — the study of control and communication in complex systems. By creating the right feedback loops and control structures, good practices become the path of least resistance:
- Fast feedback loops (pre-commit hooks) catch issues immediately
- Progressive gates (pre-push, CI/CD) balance thoroughness with productivity
- Isolation (session-based development) prevents conflicts and enables parallel work
The central insight is agent equivalence: the incentive structures that guide human developers guide AI agents equally well. This isn't coincidence — it is design. We do not need to teach AI agents to follow best practices. We create an environment where following best practices is the only way to succeed, the same as for humans.
For the full theoretical background, see docs/theory-of-operation.md.
Minsky follows a clean architecture with domain logic separated from adapters and infrastructure. The same domain operations (task management, session lifecycle, PR creation) work whether accessed via CLI or MCP. See docs/architecture.md for details.
We welcome contributions. See CONTRIBUTING.md for guidelines.
MIT — See LICENSE for details.
Named after Marvin Minsky, whose "Society of Mind" theory inspired the idea that intelligence emerges from the coordination of simple processes. Just as Minsky proposed that minds are societies of simpler agents, this tool orchestrates development tools into coherent workflows.
The organizational cybernetics principles draw from Stafford Beer's Viable System Model: organizations of humans or AI agents need the same control structures to function effectively.