Cyrus AI Agent Platform

The Cyrus monorepo is composed of several specialized packages, each with a distinct scope. Developers can use these packages independently or combine them to build complex applications like CLI tools or Electron-based agents.

Core Packages

• @cyrus/core: Contains domain models (Session, Issue, Workspace, Comment), session lifecycle management, and shared TypeScript types.
• @cyrus/claude-parser: Responsible for parsing Claude's stdout/stderr, specifically handling streaming JSON and emitting typed ClaudeEvents.
• @cyrus/claude-runner: Manages the lifecycle of the Claude CLI process, including spawning processes, sending prompts, and configuring tools.
• @cyrus/ndjson-client: Provides NDJSON streaming communication with an edge proxy, handling OAuth authentication and webhook events.
• @cyrus/edge-worker: The primary orchestrator. It connects to the edge proxy, processes Linear webhooks, manages Claude sessions, and posts responses back to Linear.

Claude Code discovers skills located in the <repo>/.claude/skills/ directory. The discovery mechanism depends on how the repository is added to the session:

1. Single-repo sessions: If the current working directory (cwd) is the repository itself, the CLI automatically discovers skills in <cwd>/.claude/skills/.
2. Multi-repo or Subdirectory sessions: If a repository is a subdirectory of the cwd (or a sibling in a workspace container), the skills will not be discovered automatically. You must use the --add-dir <dir> flag to explicitly add the directory. This flag triggers the auto-loading of .claude/skills/ from that specific directory.

Important: The skills flag in the SDK is a context filter, not a discovery mechanism. It determines which already discovered skills are enabled. If a skill is not discovered (e.g., because --add-dir was not used for a subdirectory), it cannot be enabled via the skills filter.

The Stop hook is a mechanism used to intercept a session stop attempt. When implemented via RunnerConfigBuilder.buildStopHook(), it can block the first stop attempt to provide guidance to the agent (e.g., reminding them to commit or push code).

Behavioral Logic:

• First Stop Attempt: If the hook returns decision: "block" and a reason: "...", the SDK blocks the stop and injects a synthetic user message containing that reason text. This ensures the agent receives the guidance in its next turn.
• Second Stop Attempt: When a stop is triggered while a hook is active (stop_hook_active === true), the hook should return an empty object {} to allow the session to complete cleanly without an infinite loop.

SDK Signaling: Whenever a Stop hook returns decision: "block", the SDK emits a system/notification event with the key "stop-hook-error". This is a standard signal that a hook has intervened and does not indicate a code error.

The Codex app-server implements a session resumption lifecycle designed for production environments where follow-up comments occur after a turn has fully completed.

The Workflow:

1. Turn Completion: A turn finishes and the session is marked as completed (e.g., subtype: success).
2. Resumption Trigger: When a new interaction occurs, the EdgeWorker calls resumeAgentSession.
3. Session Identification: If a previous session exists, needsNewSession is set to false and a resumeSessionId is provided.
4. Runner Initialization: The CodexRunner is initialized with the resumeSessionId.
5. Context Recall: The backend uses thread/resume to load the prior context into a fresh app-server process, allowing the agent to recall information from previous turns.

[resumeAgentSession] needsNewSession=false, resumeSessionId=019e952a-cc98-7621-aec4-7859117e9c6b

The validation loop is a core mechanism in Cyrus that ensures code quality by automatically handling test failures. The lifecycle follows this pattern:

1. Coding Activity: The agent implements the requested feature.
2. Verifications: The agent runs the test suite and type checking.
3. Failure Detection: If tests fail, the AgentSessionManager identifies the failure reason and triggers the fixer.
4. Validation Fixer: A specialized subroutine (validation-fixer) is invoked to resolve the identified bugs.
5. Retry/Re-verification: The agent re-runs the verifications subroutine. If successful, it advances to the next stage (e.g., git-gh); if not, it continues the loop up to a maximum number of iterations.

Key Events

• validationLoopIteration: Fired when a validation attempt completes (pass or fail).
• validationLoopRerun: Fired when re-running verifications after a fix has been applied.

Orchestration state must be tracked in your internal responses, NOT in Linear comments to the current issue. Use the following structured formats for tracking:

Orchestration Status

Track the lifecycle of sub-issues:

• Completed: List of merged sub-issues with verification results.
• Active: The sub-issue currently being executed.
• Pending: Queued sub-issues.
• Blocked: Issues awaiting resolution.

Verification Log

For each sub-issue, maintain a detailed log:

• [Sub-Issue ID]
• Verification Commands: Commands executed.
• Expected Outcomes: What was expected.
• Actual Results: What actually occurred.
• Evidence: Screenshots, logs, test outputs.
• Visual Confirmation: Confirmation that screenshots were taken and visually inspected.
• Status: PASSED, FAILED, or PARTIAL.
• Notes: Additional observations.

Decision and Risk Tracking

• Key Decisions: Record decisions and their rationales.
• Risks & Mitigations: Record identified risks and their mitigation strategies.

## Orchestration Status
**Completed**: [List of merged sub-issues with verification results]
**Active**: [Currently executing sub-issue]
**Pending**: [Queued sub-issues]
**Blocked**: [Issues awaiting resolution]

## Verification Log
**[Sub-Issue ID]**:
- Verification Commands: [Commands executed]
- Expected Outcomes: [What was expected]
- Actual Results: [What occurred]
- Evidence: [Screenshots, logs, test outputs]
- Visual Confirmation: [Screenshots taken and read/viewed with confirmation of visual elements]
- Status: [PASSED/FAILED/PARTIAL]
- Notes: [Additional observations]

## Key Decisions
- [Decision]: [Rationale]

## Risks & Mitigations
- [Risk]: [Mitigation strategy]