component-refactoring

Dorothy

A beautiful desktop app to orchestrate your Claude Code ,Codex, Gemini, Grok and local agents. Deploy, monitor, and debug — all from one delightful interface. Free and open source.

Table of Contents

• Why Dorothy
• Core Features
• Automations
• Kanban Task Management
• Scheduled Tasks
• Remote Control
• Vault
• SocialData (Twitter/X)
• Google Workspace
• MCP Servers & Tools
• Installation
• Architecture
• Project Structure
• Tech Stack
• Configuration & Storage
• Development
• Contributing
• License

---

Why Dorothy

AI CLI tools are powerful — but it runs one agent at a time, in one terminal. Dorothy removes that limitation:

• Run 10+ agents simultaneously across different projects and codebases
• Automate agent workflows — trigger agents on GitHub PRs, issues, and external events
• Delegate and coordinate — a Super Agent orchestrates other agents via MCP tools
• Manage tasks visually — Kanban board with automatic agent assignment
• Schedule recurring work — cron-based tasks that run autonomously
• Control from anywhere — Telegram and Slack integration for remote management

---

Core Features

Parallel Agent Management

Run multiple agents simultaneously, each in its own isolated PTY terminal session. Agents operate independently across different projects, codebases, and tasks.

Capabilities:

• Spawn unlimited concurrent agents across multiple projects
• Each agent runs in an isolated terminal with full PTY support
• Assign skills, model selection (sonnet, opus, haiku), and project context per agent
• Send interactive input to any running agent in real-time
• Real-time terminal output streaming per agent
• Agent lifecycle management: idle → running → completed / error / waiting
• Secondary project paths via --add-dir for multi-repo context
• Git worktree support for branch-isolated development
• Persistent agent state across app restarts
• Autonomous execution mode (--dangerously-skip-permissions) for unattended operation

Super Agent (Orchestrator)

A meta-agent that programmatically controls all other agents. Give it a high-level task and it delegates, monitors, and coordinates the work across your agent pool.

• Creates, starts, and stops agents programmatically via MCP tools
• Delegates tasks based on agent capabilities and assigned skills
• Monitors progress, captures output, and handles errors
• Responds to Telegram and Slack messages for remote orchestration
• Can spin up temporary agents for one-off tasks and clean them up after

Usage Tracking

Monitor Claude Code API usage across all agents — token consumption, conversation history, cost tracking, and activity patterns.

Skills & Plugin System

Extend agent capabilities with skills from skills.sh and the built-in plugin marketplace.

• Code Intelligence: LSP plugins for TypeScript, Python, Rust, Go, and more
• External Integrations: GitHub, GitLab, Jira, Figma, Slack, Vercel
• Development Workflows: Commit commands, PR review tools
• Install skills per-agent for specialized task handling

Settings Management

Configure Claude Code settings directly — permissions, environment variables, hooks, and model defaults.

---

Automations

Automations poll external sources, detect new or updated items, and spawn Claude agents to process each item autonomously. This enables fully automated CI/CD-like workflows powered by AI.

Supported Sources

Execution Pipeline

1. Scheduler triggers the automation on its cron schedule or interval
2. Poller fetches items from the source (e.g., GitHub PRs via gh CLI)
3. Filter applies trigger conditions (event type, new vs. updated)
4. Deduplication skips already-processed items using content hashing
5. Agent spawning — a temporary agent is created for each item
6. Prompt injection — item data injected via template variables
7. Autonomous execution — agent runs with full MCP tool access
8. Output delivery — agent posts results to Telegram, Slack, or GitHub comments
9. Cleanup — temporary agent is deleted after completion

Template Variables

Use these in your agentPrompt and outputTemplate:

GitHub Variables

JIRA Variables

Example: Automated PR Review Bot

create_automation({
  name: "PR Code Reviewer",
  sourceType: "github",
  sourceConfig: '{"repos": ["myorg/myrepo"], "pollFor": ["pull_requests"]}',
  scheduleMinutes: 15,
  agentEnabled: true,
  agentPrompt: "Review this PR for code quality, security issues, and performance. PR: {{title}} ({{url}}). Description: {{body}}",
  agentProjectPath: "/path/to/myrepo",
  outputGitHubComment: true,
  outputSlack: true
})

Example: JIRA Issue Processor

create_automation({
  name: "JIRA Task Agent",
  sourceType: "jira",
  sourceConfig: '{"projectKeys": ["PROJ"], "jql": "status = Open"}',
  scheduleMinutes: 5,
  agentEnabled: true,
  agentPrompt: "Work on JIRA issue {{key}}: {{summary}}. Description: {{body}}. Priority: {{priority}}.",
  agentProjectPath: "/path/to/project",
  outputJiraComment: true,
  outputJiraTransition: true,
  outputTelegram: true
})

JIRA automations also create Kanban tasks automatically in the backlog, allowing agents to pick them up via the auto-assignment system.

---

Kanban Task Management

A task board integrated with the agent system. Tasks flow through columns and can be automatically assigned to agents based on skill matching.

Workflow

Backlog → Planned → Ongoing → Done

• Priority levels: Low, Medium, High
• Progress tracking: 0-100% per task
• Agent assignment: Assign tasks to specific agents or let the system auto-assign
• Labels and tags: Organize and filter tasks
• Skill requirements: Define required skills — the system matches tasks to capable agents

Automatic Agent Assignment

The kanban-automation service continuously watches for new tasks and:

1. Matches task skill requirements against available agents
2. Creates new agents if no matching agent exists
3. Assigns the task and moves it to `ongoin