Senior

Your 24/7 team of senior engineers

A desktop AI multi-agent harness built for long-horizon software tasks

Senior is an Electron desktop AI multi-agent harness that turns requirement intake into structured PRDs, then orchestrates long-horizon engineering tasks through staged AI execution with human gates.

From requirement evaluation to PRD design, technical review, coding, QA, and deployment notes, Senior keeps every stage traceable with artifacts and run history.

Installation · Quick Start · How It Works · Contributing

Contributing Guide · Security Policy

简体中文 | 繁體中文 | Español | Deutsch | Français | 日本語

Most AI tooling stops at chat. Senior is designed as your always-on engineering team for long-horizon software delivery, with explicit workflow state machines:

• Requirements move through explicit stages: pending -> evaluating -> prd_designing -> prd_reviewing -> queued/canceled
• Tasks move through delivery stages: idle -> arch_designing -> tech_reviewing -> coding -> qa_reviewing -> deploying -> done
• Every stage writes artifacts and trace messages so teams can inspect what happened instead of guessing
• Human intervention is first-class for review gates and revisions

Senior is built for teams that want AI execution with process control, not just prompt-response interaction.

• Dual auto processors for requirement and task execution loops
• Project workspace binding so agent runs are executed against selected project directories
• Bilingual UI (en-US and zh-CN) with local preference persistence
• Electron IPC boundary between renderer and main process services

• Node.js 20+ (recommended)
• npm 10+
• A machine with desktop GUI support (for Electron)
• Runtime credentials configured for at least one supported Agent SDK:
  • Claude Agent SDK (default)
  • Codex SDK (Node SDK; reads provider config from ~/.codex/config.toml, OPENAI_API_KEY optional)

git clone https://github.com/zhihuiio/senior.git
cd senior
npm install
npm run dev

npm run build
npm run preview

npm run pack:dmg

After packaging, installer artifacts are written to release/:

• Senior-<version>-arm64.dmg
• Senior-<version>-arm64.zip
• Senior-<version>-arm64.dmg.blockmap

Generate a Homebrew cask file from the packaged DMG:

npm run homebrew:cask

This command creates release/homebrew/senior.rb with the correct sha256 and release URL template. Publish this file to your Homebrew tap repository (for example homebrew-tap/Casks/senior.rb) after uploading release assets.

1. Launch the app with npm run dev.
2. Create or select a project directory.
3. Add requirements in the workspace.
4. Start the Requirement Auto Processor to evaluate and draft PRDs.
5. Review queued tasks and start the Task Auto Processor.
6. Inspect stage traces and artifacts, then provide human feedback when a gate pauses execution.

Tip: you can also manually orchestrate specific tasks and reply directly in task human-conversation flows.

┌─────────────────────────────────────────────────────────────────────┐
│                           Senior Desktop                            │
│  ┌───────────────┐   IPC   ┌─────────────────────────────────────┐  │
│  │ React Renderer│◄───────►│ Electron Main Services             │  │
│  │ (UI + State)  │         │ - project/requirement/task service │  │
│  └───────────────┘         │ - auto processors                  │  │
│                            │ - stage run + trace management     │  │
│                            └───────────────┬─────────────────────┘  │
│                                            │                        │
│                            ┌───────────────▼─────────────────────┐  │
│                            │ Agent SDK Strategy Layer            │  │
│                            │ - Claude Agent SDK (default)        │  │
│                            │ - Codex SDK                         │  │
│                            └───────────────┬─────────────────────┘  │
│                                            │                        │
│                ┌───────────────────────────▼─────────────────────┐  │
│                │ Local data                                      │  │
│                │ - SQLite app.db (Electron userData)            │  │
│                │ - .senior/tasks/<taskId> artifacts              │  │
│                └─────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

stateDiagram-v2
  [*] --> ReqPending: create requirement
  ReqPending: Requirement.pending
  ReqEvaluating: Requirement.evaluating
  ReqPrdDesigning: Requirement.prd_designing
  ReqPrdReviewing: Requirement.prd_reviewing
  ReqQueued: Requirement.queued
  ReqWaitingHuman: waitingContext=prd_review_gate
  ReqCanceled: Requirement.canceled

  ReqPending --> ReqEvaluating: start requirement processor
  ReqEvaluating --> ReqPrdDesigning: evaluation passed
  ReqEvaluating --> ReqCanceled: evaluation failed
  ReqPrdDesigning --> ReqPrdReviewing: PRD draft generated
  ReqPrdReviewing --> ReqQueued: approved
  ReqPrdReviewing --> ReqPrdDesigning: review_fail (rework)
  ReqPrdReviewing --> ReqWaitingHuman: review_fail > 3
  ReqWaitingHuman --> ReqPrdDesigning: human reply / revise

  ReqQueued --> TaskIdle: create task from requirement
  TaskIdle: Task.idle
  TaskArchDesigning: Task.arch_designing
  TaskTechReviewing: Task.tech_reviewing
  TaskWaitingHuman: Task.waiting_human
  TaskCoding: Task.coding
  TaskQaReviewing: Task.qa_reviewing
  TaskDeploying: Task.deploying
  TaskDone: Task.done

  TaskIdle --> TaskArchDesigning: start task processor
  TaskArchDesigning --> TaskTechReviewing
  TaskTechReviewing --> TaskCoding
  TaskTechReviewing --> TaskArchDesigning: review_fail (rework)
  TaskTechReviewing --> TaskWaitingHuman: review_fail > 3
  TaskCoding --> TaskQaReviewing
  TaskCoding --> TaskWaitingHuman: coding gate
  TaskQaReviewing --> TaskDeploying
  TaskQaReviewing --> TaskCoding: qa_fail (rework)
  TaskQaReviewing --> TaskWaitingHuman: qa_fail > 3

  TaskWaitingHuman --> TaskArchDesigning: human revise (arch gate)
  TaskWaitingHuman --> TaskCoding: human revise (coding gate)
  TaskWaitingHuman --> TaskTechReviewing: human force_pass (arch gate)
  TaskWaitingHuman --> TaskQaReviewing: human force_pass (coding gate)
  TaskWaitingHuman --> TaskIdle: human cancel
  TaskWaitingHuman --> TaskWaitingHuman: human revise note

  TaskDeploying --> TaskDone
  TaskDone --> [*]

src/
  main/                 Electron main process, services, DB, agents
  preload/              Secure API bridge for renderer
  renderer/             React UI, hooks, i18n, components
  shared/               Shared types and IPC contracts
tests/
  main/agents/          Agent behavior tests
resources/
  senior_v2.png         Project image asset

npm run dev                  # Start Electron + Vite in development
npm run build                # Build main/preload/renderer bundles
npm run pack:dmg             # Build and package macOS DMG artifacts
npm run pack:mac             # Build and package all configured macOS targets
npm run release:mac          # Build and publish macOS release artifacts
npm run homebrew:cask        # Generate Homebrew cask file from packaged DMG
npm run preview              # Preview built app
npm run test:freeform-agent  # Run freeform agent tests

npm install also triggers electron-rebuild -f -w better-sqlite3 via postinstall.

• SQLite database file: <electron-userData>/app.db
• Task artifacts directory: <project-path>/.senior/tasks/<taskId>/
• Stage artifacts commonly include:
  • arch_design.md
  • tech_review.json
  • code.md
  • qa.json
  • deploy.md

Senior stores stage run status (running/succeeded/failed/waiting_human), round metadata, and agent traces so interrupted runs can be repaired and resumed safely.

• Requirement stage pipeline (evaluation, PRD design, review)
• Task stage orchestration with review gates
• Requirement and task auto processors
• Stage run trace persistence and timeline visualization
• Artifact reading from workspace task directories
• Packaged macOS DMG workflow and Homebrew cask generation
• Expanded test coverage beyond freeform agent tests
• More UI languages beyond English and Simplified Chinese

Contributions are welcome, especially in these areas:

• Workflow reliability and edge-case handling
• Additional tests and fixtures
• UI/UX improvements for traceability and operator control
• Internationalization and docs quality

Development bootstrap:

npm install
npm run dev

This project is licensed under the Senior Community License. See LICENSE for details.