* docs: add design research artifacts — briefs, token reference, screenshots
Comprehensive design research package for the ao dashboard, session
detail page, and orchestrator terminal. Produced via competitive analysis
of 14 products (Linear, Vercel, Railway, Fly.io, Inngest, WandB, LangSmith,
Supabase, and more) + Playwright CSS extraction from live sites + full
codebase audit.
Artifacts:
- docs/design/design-brief.md Main design brief (v2, Playwright-updated)
- docs/design/session-detail-design-brief.md /sessions/[id] design spec
- docs/design/orchestrator-terminal-design-brief.md Orchestrator page spec
- docs/design/token-reference.css Drop-in CSS replacement for globals.css
- docs/design/competitive-analysis-raw.md Raw research notes, all 14 sites
- docs/design/design-brief-v1.md Original text-only brief (pre-Playwright)
- docs/design/README.md Index + research methods summary
- docs/design/screenshots/linear-homepage.png Playwright-captured screenshot
- docs/design/screenshots/railway-homepage.png Playwright-captured screenshot
Key findings:
- Linear CSS token values verified via Playwright (body bg #08090A, accent
#7070FF, Berkeley Mono monospace, type scale, radius, transitions)
- Recommended palette: #0C0C11 base (blue-cast dark vs current GitHub #0d1117)
- Highest-impact change: load Inter Variable via next/font/google
- Orchestrator terminal needs visual differentiation (violet accent, status strip)
- token-reference.css is ready to drop into packages/web/src/app/globals.css
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(web): redesign dashboard, session detail, and orchestrator terminal
Implements a cohesive dense dark-mode design system across all three main views.
- New color token palette: #0c0c11 base, #141419 surface, #1c1c25 elevated
- Accent blue #5b7ef8, status semantics (ready/error/attention/working/idle/done)
- Violet accent #a371f7 reserved for orchestrator
- Inter Variable + JetBrains Mono loaded via next/font with CSS variables
- activity-pulse keyframe for live agent dots
- AttentionZone header: dot + label + flex divider + count pill + chevron
- Sessions laid out in responsive 1→2→3 column grid
- Solid green merge button (translateY hover), no confirm() dialog
- Breadcrumb nav: ← Agent Orchestrator / {session-id} [orchestrator badge]
- CSS 8×8px activity dot with pulse animation replaces emoji labels
- Merge-ready state: green-bordered banner with checkmark icon
- Orchestrator sessions show zone counts strip (merge/respond/review counts)
- xterm.js dark theme (#0a0a0f bg, #d4d4d8 fg, full 16-color ANSI palette)
- variant prop: "agent" (blue cursor) vs "orchestrator" (violet cursor)
- Dynamic height prop instead of fixed 600px; fullscreen toggle with SVG icons
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* refactor(web): strip rainbow stats, clean header, IBM Plex Sans typography
- Replace Inter with IBM Plex Sans (technical tool aesthetic, distinctive numerics)
- Replace 4-color big-number stats bar with a single compact inline status line
in the header: "35 sessions · 1 working · 9 PRs" — no decorative colors
- Remove the two-tone "Agent (blue) Orchestrator (white)" title — just "Orchestrator"
- Remove ClientTimestamp (useless) — replaced by orchestrator nav link
- Zone headers: colored dot only (semantic), neutral uppercase label, plain count
— removes the rainbow-colored label text that read as a widget template
- Add subtle radial gradient glow at top of page for depth
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(web): kanban layout, amber accent, full-width, bigger stats
- Switch accent from blue (#5b7ef8) to amber/gold (#d18616) throughout
- Replace grid layout with horizontal Kanban columns for active zones
(merge, respond, review, pending, working), Done stays full-width below
- Remove max-w-[1100px] constraint — full viewport width
- Header stats numbers 20px bold (was 12px), orchestrator link is now a
visible bordered button
- AttentionZone gains variant="column" for Kanban mode (compact header
with count pill, vertical card stack)
- Update all hardcoded rgba(91,126,248,...) in SessionCard to amber
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(web): layout, alert sizing, column order, button feel
- Kanban column order: working→pending→review→respond→merge
(left = in progress, right = ready to ship)
- Columns use flex-1 min-w-[200px] to fill available width
instead of fixed 260px leaving half the page empty
- Alert badges: inline-flex wrapper prevents stretching to full
row width when wrapping
- Terminal button: add bg-subtle fill so it reads as a button
- PR number (#91): remove opaque pill background, now plain
amber text link — clearly a hyperlink
- Merge PR button: pt-0.5 spacer above the action area
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(web): don't cache rate-limited partial PR data
When GitHub rate limits fire, enrichSessionPR was caching the
bad partial data (0 additions, CI failing) for 60 seconds, causing
the dashboard to show incorrect data for the full TTL window.
- Skip cache write when majority of API calls failed
- Downgrade console.error → console.warn (this is handled/expected)
The next page refresh will retry live API calls, so data recovers
as soon as the rate limit window resets.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(web): graceful GitHub API rate limit handling in UI
When the GitHub plugin hits rate limits, the dashboard now:
- Shows a single amber banner: "GitHub API rate limited — PR data
(CI status, review state, sizes) may be stale. Will retry on
next refresh."
- Hides CI badge, review decision, and size pill on PR cards
(they'd show wrong values: +0 -0 XS, CI failing)
- Shows a subtle "⚠ PR data rate limited" note on affected cards
instead of misleading alert badges
- Skips CI/review/conflict-based attention zone classification
for rate-limited PRs (prevents sessions moving to Review due
to phantom "CI failing" from the fallback value)
- Doesn't cache partial rate-limited data so next refresh retries
live API calls as soon as the rate limit window resets
What still works when rate limited:
- Session ID, title, branch, PR number/link
- Session activity status (working/spawning/etc.)
- Merge button if mergeability was already cached
- Restore/terminate/send actions
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(web): dashboard redesign — glassmorphism, Kanban, rate-limit handling, perf fix
Design:
- Kanban layout: active zones as flex columns (working→pending→review→respond→merge),
Done as full-width grid below
- GitHub dark color palette (main's tokens) with glassmorphic card surfaces
(rgba bg + backdrop-blur) and subtle blue/violet body gradient
- Activity state shown as labeled pill (● active / ● idle etc.) instead of bare dot
- Session card: title on its own row, larger font, inline-flex alert badges (no stretch)
- PR number rendered as plain accent link, not a blue pill badge
- Terminal button has background fill to feel like a button
- Info circle icon replaces alarming warning triangle for rate-limit indicators
- "1 working" → "1 active" in header stats
- PR table constrained to max-w-[900px] and centered
- Orchestrator session no longer uses purple accent
Rate limiting:
- isPRRateLimited() helper; getAttentionLevel() skips PR classification when limited
- Rate-limited banner in Dashboard; suppressed CI/size/review badges in PRStatus
- SessionCard shows subtle "PR data rate limited" indicator; getAlerts() returns []
- serialize.ts: rate-limited enrichment results cached for 5 min (not 60s) to stop
retrying 168 failing API calls every minute
Performance:
- page.tsx: 4s hard timeout on PR enrichment — serves stale data fast instead of
blocking SSR for 75s under rate limiting
- cache.ts: TTLCache.set() accepts optional ttl override for per-entry control
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: suppress stale size/CI/review in PR table when rate limited
PRTableRow now shows "—" for size, CI, and review columns when GitHub
API is rate limited, matching the card view which already hides these.
Prevents misleading "+0 -0 XS" size and "needs review" labels from the
default fallback values.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: 3D card effect with depth shadow and top-edge shine
Cards now clearly pop against the dark background:
- Solid gradient bg (rgba(28,36,47) → rgba(18,23,31)) instead of
near-invisible rgba(22,27,34,0.8) surface
- Layered box-shadow: contact shadow + diffuse depth + inset top highlight
that simulates light hitting the card's top edge (the "shine")
- Hover: card lifts 2px with deeper shadow
- Merge-ready: green-tinted bg with green ambient glow + stronger lift on hover
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: restore text legibility inside session cards
The darker solid card gradient made muted/secondary text nearly
invisible — #484f58 (text-muted) had only ~2:1 contrast on the
new card bg. Override the color tokens locally within .session-card
to GitHub's established dark-mode legibility values:
--color-text-muted: #484f58 → #656d76 (3.8:1 on card bg)
--color-text-secondary: #7d8590 → #8b949e (6.2:1 on card bg)
--color-text-tertiary: #484f58 → #656d76
Scoped to .session-card so the rest of the UI is unchanged.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: address bugbot comments — fonts, review zone, ActivityDot, orchestrator btn
- layout.tsx: add IBM Plex Sans weight 700 (was missing, font-bold falling
back to 600)
- DirectTerminal.tsx: use "IBM Plex Mono" instead of unloaded "JetBrains Mono"
- SessionDetail.tsx: add review zone to OrchestratorStatusStrip (was omitted,
sessions with CI failures were invisible in the strip)
- ActivityDot.tsx: extract shared component, remove duplicate implementations
in SessionCard.tsx and SessionDetail.tsx
- Dashboard.tsx: redesign orchestrator button with 3D glass style matching
card aesthetic (blue-tinted bg, depth shadow, hover lift)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(web): lint — eqeqeq, duplicate import, unused var
- ActivityDot.tsx: != → !== (eqeqeq rule)
- PRStatus.tsx: merge duplicate @/lib/types imports into one
- SessionCard.tsx: remove unused activityIcon import
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(web): elevate session detail + orchestrator page design
- Nav: glass backdrop-blur effect with chevron back link
- Header: detail-card 3D treatment with left-border accent keyed to activity color
- Meta chips: bordered pill style with subtle bg instead of flat text
- Status tag: pill badge for status instead of plain text
- PR card: detail-card 3D treatment, border-color reflects PR state
- PR merged badge: purple pill instead of gray text
- Unresolved count: red pill badge in section header
- Blockers section: renamed "Issues" → "Blockers"
- Terminal section: colored bar indicator instead of plain label
- Orchestrator status strip: total agent count + per-zone colored pills
- globals.css: add .nav-glass and .detail-card classes
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(web): fetchZoneCounts parses body.sessions, delayed 2s to avoid contention
The /api/sessions endpoint returns `{ sessions: [...] }` not a bare array.
fetchZoneCounts was treating the whole response object as an array, so
zone counts were always zero on the orchestrator detail page.
Also delays the initial fetchZoneCounts call by 2s so it doesn't contend
with the session fetch on page load (both hit /api/sessions which is slow
when GitHub enrichment is running).
Also includes: Playwright kill-Chrome-for-Testing tip in CLAUDE.md,
toned-down detail-card shadow in globals.css.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* perf+test(web): cache-first PR enrichment, skip exited sessions, fix component tests
Performance improvements:
- enrichSessionPR() now accepts cacheOnly option and returns boolean
- /api/sessions/[id]: serve from cache immediately, only block on first load
- /api/sessions: skip PR enrichment for EXITED sessions (no longer changing)
- cache: increase default TTL from 60s to 5 minutes
Test fixes (match redesigned SessionCard + AttentionZone):
- "restore session" (header) → "restore"; expanded panel still shows "restore session"
- "merge PR #N" → "Merge PR #N" (capital M)
- "CI status unknown" → "CI unknown"
- "ask to fix CI" / "ask to fix CI" → "ask to fix"
- "terminate session" → "terminate"
- Zone labels: RESPOND/WORKING/DONE → Respond/Working/Done (CSS uppercase is visual only)
- "working" zone no longer collapsed by default; collapse tests now use "done" zone
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(core): ActivityDetection with timestamp propagation
- Add ActivityDetection interface { state, timestamp? } to types.ts
- Agent getActivityState() returns ActivityDetection | null instead of
ActivityState | null, allowing timestamp from JSONL mtime to propagate
- session-manager updates session.lastActivityAt when detected.timestamp
is more recent — fixes "active 22h ago" showing stale timestamps
- Update all agent plugins (claude-code, aider, codex, opencode) to
return ActivityDetection objects
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(web): dismissible rate limit banner + 60min rate-limit cache TTL
- Add X dismiss button to GitHub API rate limit banner in Dashboard.tsx
so it can be closed during demos
- Extend rate-limited PR cache TTL from 5min to 60min — GitHub GraphQL
rate limits reset hourly, no point retrying every 5 minutes
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(web): address Cursor Bugbot review comments on PR #125
- Dashboard StatusLine: active sessions count now uses var(--color-status-working)
(blue) instead of neutral text color, matching the design system semantics
- SessionCard: isReadyToMerge now guards against rate-limited state — a card
with stale cached mergeability data won't show green merge-ready styling
- DirectTerminal: add `variant` to useEffect dependency array (was missing,
causing stale cursor/selection colors if variant changed after mount)
- agent-aider: include `timestamp: chatMtime` in all ActivityDetection returns,
matching the pattern used by agent-claude-code (enables accurate lastActivityAt)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(ci): resolve lint, typecheck, and test failures
Lint:
- Remove unused parseJsonlFile function (superseded by parseJsonlFileTail)
- Remove dead lastLogModified stat() call in getSessionInfo (field was
removed from AgentSessionInfo but the filesystem read was left behind)
Typecheck + Tests (ActivityDetection):
- session-manager.test.ts: update mocks to return { state: "active" } /
{ state: "idle" } instead of bare strings — getActivityState() returns
ActivityDetection | null, not ActivityState | null
- integration tests (aider, claude-code, codex, opencode): update imports
from ActivityState → ActivityDetection, variable types, comparisons
(activityState?.state !== "exited"), and assertions (?.state).toBe()
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: parseJsonlFileTail uses readFile for small files; enrich exited sessions with PRs
- parseJsonlFileTail now calls stat() then readFile() for files smaller than
maxBytes, falling back to open()/handle.read() only for large files. This
fixes the test infrastructure (which mocks readFile but not open) and also
fixes a scope bug where `offset` was declared inside an inner try block but
referenced outside both try blocks.
- Math.max(0, NaN) returns NaN not 0, so size must default to 0 when stat
returns a mock without a size field: `const { size = 0 } = await stat(...)`.
- Update activity-detection.test.ts: getActivityState() now returns
ActivityDetection objects, so tests use (await ...)?.state comparisons.
- Remove stale lastLogModified test (field was removed from AgentSessionInfo).
- Remove EXITED skip guard from api/sessions/route.ts: exited sessions can
still have open, merge-ready PRs that need enrichment on the dashboard.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: comprehensive code review fixes — tests, timestamps, UI correctness
Address gaps identified in code review of the ActivityDetection PR:
Core / Session Manager:
- Add `timestamp` to all `{ state: "exited" }` returns in all 4 agent plugins
(claude-code, aider, codex, opencode) using consistent `exitedAt = new Date()` pattern
- Add 2 new session-manager tests: timestamp propagation when detection timestamp
is newer, and no-downgrade when detection timestamp is older
- Fix `parseJsonlFileTail` lint error: remove useless `= 0` initializer (value was
always overwritten before use; catch block returns early)
Web package — tests:
- Fix 3 `api-routes.test.ts` failures: `sessionsGET()` needs a Request object since
the route reads `request.url` for `?active=true` query param
- Fix `serialize.test.ts` rate-limit test: spy on `console.warn` (what the code uses)
not `console.error`
- Add 5 `ActivityDot` component tests covering all activity states, unknown states,
null activity, and dotOnly mode
Web package — UI correctness:
- Fix `relativeTime()` in SessionDetail to guard against invalid/empty ISO strings
- Fix timer Map leak: add `timersRef.current.clear()` in cleanup effect after forEach
- Add `encodeURIComponent` to sessionId in message fetch URL
Server — race condition fix:
- Guard `activeSessions.delete` in pty.onExit, ws.on("close"), and ws.on("error")
against stale handlers deleting a newly-registered session with the same ID.
Fixes flaky integration test where afterEach's pty.kill() fired asynchronously
after the next test had already set up a new session with the same session ID.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(web): narrow PREnrichmentData types to eliminate unsafe casts in serialize
PREnrichmentData.ciStatus and .reviewDecision were typed as string,
requiring unsafe `as` casts when reading from cache into DashboardPR.
Narrow them to the same literal union types used by DashboardPR, making
the casts unnecessary. Also narrow ciChecks[].status to match CoreCICheck.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: implement seamless onboarding with enhanced documentation
- Add comprehensive README.md (18KB) with quick start, core concepts, and FAQ
- Add detailed SETUP.md (16.5KB) with prerequisites, integration guides, and troubleshooting
- Add examples/ directory with 5 ready-to-use config templates:
- simple-github.yaml: Minimal GitHub setup
- linear-team.yaml: Linear integration
- multi-project.yaml: Multiple repos
- auto-merge.yaml: Aggressive automation
- codex-integration.yaml: Using Codex agent
- Add environment detection (git repo, remote, branch, auth status)
- Auto-fill prompts with smart defaults from detected environment
- Add prerequisite validation (git, tmux, gh CLI)
- Show actionable next steps and warnings
- Parse owner/repo from git remote automatically
- Detect LINEAR_API_KEY and SLACK_WEBHOOK_URL in environment
- Prompt for Linear team ID when Linear tracker selected
- Format all files with Prettier for consistency
Reduces onboarding time from 30+ minutes to ~5 minutes:
1. Install CLI: `npm install -g @composio/ao-cli`
2. Run init: `ao init` (auto-detects everything)
3. Spawn agent: `ao spawn my-project ISSUE-123`
Users no longer need to:
- Manually parse git remote URLs
- Look up current branch names
- Remember YAML syntax
- Search for Linear team IDs
- Debug missing prerequisites
- ✅ pnpm build - All packages compile
- ✅ pnpm typecheck - No TypeScript errors
- ✅ pnpm lint - No new linting issues
- ✅ pnpm format - All files formatted
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* docs: update installation instructions to reflect npm not yet published
Package is not published to npm yet, so users must build from source.
Updated README.md and SETUP.md to:
- Make 'build from source' the primary installation method
- Add note that npm publishing is coming soon
- Include pnpm as a prerequisite
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* feat: add ao init --auto --smart for zero-config setup
Implements intelligent config generation with project type detection.
## What's New
### ao init --auto
- Zero prompts - auto-generates config with smart defaults
- Detects: git repo, remote, branch, languages, frameworks, tools
- Generates project-specific agentRules based on detected tech stack
### Project Detection
- Languages: TypeScript, JavaScript, Python, Go, Rust
- Frameworks: React, Next.js, Vue, Express, FastAPI, Django, Flask
- Tools: pnpm workspaces, test frameworks
- Package managers: pnpm, yarn, npm
### Rule Templates
Created templates for:
- base.md - Universal best practices
- typescript.md - TS strict mode, ESM, type imports
- javascript.md - Modern ES6+ patterns
- react.md - Hooks, composition, best practices
- nextjs.md - App Router, Server Components
- python.md - Type hints, PEP 8
- go.md - Error handling, defer patterns
- pnpm-workspaces.md - Monorepo commands
### Example Output
```bash
ao init --auto
# Detects:
# ✓ TypeScript + pnpm workspaces
# ✓ React + Next.js
# ✓ Vitest
# Generates:
agentRules: |
Always run tests before pushing.
Use TypeScript strict mode.
Use ESM modules with .js extensions.
Use React best practices (hooks, composition).
Before pushing: pnpm build && pnpm typecheck && pnpm lint && pnpm test
```
## Benefits
- **5 seconds** instead of 5 minutes
- **Zero config knowledge** required
- **Context-aware rules** tailored to your stack
- **Still customizable** - edit the generated config
## Future: --smart (AI-powered)
Flag added but not yet implemented. Will use Claude Code to:
- Analyze CLAUDE.md, CONTRIBUTING.md
- Read CI/CD config
- Generate custom rules based on project patterns
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: detect repo default branch instead of current branch
Fixes Bugbot issue: "Current branch wrongly suggested as default base branch"
## Problem
detectEnvironment was using `git branch --show-current` to suggest
defaultBranch in the config. If a user ran `ao init` while on a feature
branch like `feat/my-work`, the wizard would suggest that feature branch
as the default, causing agents to branch from the wrong base.
## Solution
Added detectDefaultBranch() function with 3 fallback methods:
1. git symbolic-ref refs/remotes/origin/HEAD (most reliable)
2. GitHub API via gh CLI (if ownerRepo known)
3. Check common branch names: main, master, next, develop
Now EnvironmentInfo tracks both:
- currentBranch: The checked-out branch (for display only)
- defaultBranch: The repo's base branch (for config)
## Testing
Tested on feat/seamless-onboarding branch:
- Current branch: feat/seamless-onboarding (displayed)
- Default branch: main (correctly detected for config)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: prevent duplicate framework detection in Python projects
Fixes Bugbot issue: "Duplicate frameworks when multiple Python config files exist"
## Problem
When both requirements.txt and pyproject.toml exist and mention the same
framework (e.g., FastAPI), the detection loop added it to the frameworks
array twice, causing duplicate rules in the generated config.
## Solution
Added addFramework() helper that checks if framework already exists before
adding to the array. Also prevents pytest from being set multiple times as
testFramework.
## Testing
Verified with test repo containing both files with FastAPI:
- Before: Would add 'fastapi' twice
- After: Only adds 'fastapi' once ✓
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: address Bugbot review comments
- Remove redundant conditional in --smart flag (both branches were identical)
- Include templates directory in npm package files
* fix: add existence check for base.md template file
Add existsSync guard before reading base.md to handle missing templates gracefully, consistent with other template file reads.
* fix: use direct tool invocation instead of which command
Replace 'which' with direct tool invocation (tmux -V, gh --version)
for better portability on minimal Linux systems where 'which' may
not be installed.
* fix: address Bugbot review comments
- Simplify gh auth status check to rely on exit code instead of output string
- Remove async from synchronous functions (detectProjectType, generateRulesFromTemplates)
* feat: add setup script for one-command installation
Add scripts/setup.sh that:
- Installs pnpm if not present
- Installs dependencies
- Builds all packages
- Links CLI globally
Updated README with simplified setup instructions using the script.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: correct npm link command in setup script
Remove incorrect -g flag from npm link command. The correct syntax is to cd into the package directory and run npm link without flags.
* fix: address Bugbot review comments on init command
- Validate --smart flag requires --auto (prevents silent ignore)
- Fix path validation to check user-specified path (not CWD)
These fixes address medium and low severity issues found by Cursor Bugbot
in PR #66 review.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* docs: add DirectTerminal troubleshooting and fix setup script
- Add TROUBLESHOOTING.md documenting node-pty posix_spawnp error
- Update setup.sh to rebuild node-pty from source (fixes DirectTerminal)
- Ensures seamless onboarding with working terminal out-of-the-box
Resolves DirectTerminal WebSocket failures from incompatible prebuilt binaries.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: resolve variable scope issue in init command validation
- Move path variable outside if block to fix TypeScript scope error
- Only validate path existence if projectId is provided
- Use inline tilde expansion instead of missing expandHome import
Fixes build error that prevented setup.sh from completing.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: automate node-pty rebuild to eliminate terminal issues
- Add postinstall hook to automatically rebuild node-pty after pnpm install
- Create scripts/rebuild-node-pty.js for automatic rebuild with error handling
- Remove manual node-pty rebuild from setup.sh (now automatic)
This ensures DirectTerminal works correctly on every installation without
manual intervention. Fixes posix_spawnp errors from incompatible prebuilt
binaries across different systems and installations.
Resolves issue where users would encounter blank terminals after setup.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* docs: update TROUBLESHOOTING with automatic node-pty rebuild
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* docs: add comprehensive README with quick start guide
- 3-line magical setup: clone → setup → init → start
- Architecture overview with plugin slots table
- Usage examples and auto-reaction configuration
- Links to detailed docs (SETUP.md, TROUBLESHOOTING.md, examples/)
- Philosophy: push not pull, amplify judgment
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: resolve ESLint errors in rebuild-node-pty script
- Add scripts directory configuration to eslint.config.js
- Configure Node.js globals (console, process) for scripts
- Remove unused error variable from catch block
Fixes lint CI failure.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: warn when auto mode uses placeholder repo value
- Detect when 'owner/repo' placeholder is used in --auto mode
- Show warning: 'Could not detect GitHub repository'
- Update next steps to emphasize editing config when placeholder used
- Prevents silent failures when spawning agents with invalid repo
Addresses Bugbot review comment about silent placeholder values.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: proxy ttyd through Next.js to fix "Leave Site?" dialog
Changes:
- Add Next.js rewrite to proxy /terminal-proxy/* to ttyd server
- Simplify Terminal component to use same-origin proxy URL
- Remove cross-origin fetch and error handling (no longer needed)
Why:
- Fixes "Leave Site?" confirmation dialog when navigating away from session pages
- Makes ttyd iframe same-origin with Next.js app (eliminates cross-origin restrictions)
- Simplifies architecture (no cross-origin complexity)
Note: This does NOT fix clipboard copying - that's a separate ttyd/xterm.js
limitation where clipboard operations don't work even on the raw ttyd page.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* docs: add development workflow section to CLAUDE.md
Explains:
- Build packages before running dev server (web depends on built core/plugins)
- Config file requirement (agent-orchestrator.yaml)
- Worktree-specific setup steps
This prevents the "Module not found: @composio/ao-core" error when starting
the dev server without building packages first.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: add sandbox attribute to terminal iframe to prevent "Leave Site?" dialog
Added sandbox="allow-scripts allow-same-origin allow-forms" to the terminal
iframe. This prevents the iframe's beforeunload handler from triggering a
"Leave Site?" confirmation dialog when navigating away from session pages.
The sandbox attribute restricts the iframe's ability to block navigation
while still allowing:
- Scripts (for xterm.js and WebSocket)
- Same-origin access (for terminal functionality)
- Forms (for terminal input)
Note: Clipboard copying behavior is inconsistent across sessions (works on
some but not others). This appears to be a ttyd/xterm.js limitation and is
tracked separately.
Fixes the "Leave Site?" popup reported in the issue.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* chore: remove unused proxy rewrite from next.config.js
The proxy approach was attempted but reverted in favor of the simpler
sandbox attribute solution.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: add allow-popups to sandbox for clipboard support
Some clipboard operations in browsers use popups internally. Adding
allow-popups to the sandbox attribute may help with clipboard copying.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* chore: minor formatting cleanup in SessionDetail.tsx
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* feat: add npm publishing support with @composio scope
Set up Changesets for version management, add publish metadata to all 20
packages under the @composio scope, create an unscoped wrapper package
(@composio/agent-orchestrator) for global install, and add a GitHub
Actions release workflow.
- Rename all packages from @agent-orchestrator/* to @composio/ao-*
- Add @composio/agent-orchestrator wrapper (bin shim → @composio/ao-cli)
- Add license, repository, homepage, bugs, files, engines to all packages
- Add .npmrc (access=public), MIT LICENSE file
- Add .changeset/ config with linked versioning for all packages
- Add .github/workflows/release.yml (changesets publish CI)
- Add changeset, version-packages, release scripts to root
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: exclude private web package from release build
The release script now filters out @composio/ao-web, matching the
workflow's existing exclusion and preventing a Next.js build failure
from blocking npm publishing.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Reduced CLAUDE.md from 223 to 169 lines (24% reduction).
Changes:
- Removed verbose sections (reference implementation table, redundant explanations)
- Added "Key Files" section highlighting types.ts and plugin examples upfront
- Condensed tech stack, conventions, and commands into scannable format
- Kept critical content: plugin pattern, shell security, common mistakes
Agents spawned by the orchestrator don't need special documentation - they
just read the repo's existing CLAUDE.md. The orchestrator is transparent.
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Review fixes:
- metadata: sessionId validation to prevent path traversal
- event-bus: guard appendFileSync, remove unused import
- lifecycle-manager: fix reaction retry counting (track attempts,
clear on status transition), allow retry on send failure instead
of immediate escalation, detect killed sessions in polling loop,
map session.killed to agent-exited reaction
- session-manager: validate status against union, clean up runtime
and workspace on spawn failure, kill with default plugins when
project config is missing
Lint/format fixes:
- Remove unused imports across all test files
- Replace `Function` type with typed callback in tmux tests
- Replace require() with dynamic import() in tests
- Replace dynamic delete with object spread in metadata
- Apply prettier formatting to all files
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Phase 0 complete. Establishes:
- pnpm workspace with 18 packages (core, cli, web, 15 plugins)
- Complete type definitions in packages/core/src/types.ts defining
all 8 plugin slot interfaces (Runtime, Agent, Workspace, Tracker,
SCM, Notifier, Terminal) + core service interfaces
- YAML config loader with Zod validation and sensible defaults
- Plugin registry with built-in discovery
- CLAUDE.md with conventions for spawned agents
All agents can now branch from main and implement their assigned
packages against the interfaces defined in types.ts.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
prateek