Skip to content

feat: add Ampcode agent support#120

Open
carmandale wants to merge 4 commits intosubsy:mainfrom
carmandale:feat/issue-105-add-ampcode-agent
Open

feat: add Ampcode agent support#120
carmandale wants to merge 4 commits intosubsy:mainfrom
carmandale:feat/issue-105-add-ampcode-agent

Conversation

@carmandale
Copy link
Contributor

@carmandale carmandale commented Jan 17, 2026

Summary

Adds support for Ampcode as an agent in Ralph TUI.

Changes

  • Added AmpcodeAgentPlugin in src/plugins/agents/builtin/ampcode.ts
  • Registered Ampcode in the built-in agents registry
  • Full CLI integration with:
    • Execute mode (-x) for non-interactive execution
    • Agent mode selection (free, rush, smart)
    • --dangerously-allow-all for autonomous operation
    • Stream JSON output for structured responses

Testing

  • bun run typecheck passes
  • bun run lint passes
  • bun run build passes
  • ralph-tui plugins agents shows Ampcode plugin

Usage

ralph-tui run --agent ampcode
ralph-tui run --agent ampcode --mode rush

Closes #105

Summary by CodeRabbit

  • New Features

    • New Ampcode agent plugin: amp CLI integration with streaming JSONL output, configurable modes, interactive setup and non‑interactive execution.
  • Documentation

    • Detailed TUI agent-orchestrator architecture and lifecycle guide.
    • New error reference documenting common bd/typecheck failures and remediations.
  • Chores

    • Added legacy database warning/help message with clear migration and reinitialisation steps.

✏️ Tip: You can customize this high-level summary in your review settings.

- Add AmpcodeAgentPlugin with full CLI integration
- Support for execute mode (-x), agent modes (free/rush/smart)
- --dangerously-allow-all for autonomous operation
- Stream JSON output for structured responses
- Register in built-in agent plugins

Closes subsy#105
@vercel
Copy link

vercel bot commented Jan 17, 2026

@carmandale is attempting to deploy a commit to the plgeek Team on Vercel.

A member of the Team first needs to authorize it.

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Jan 17, 2026

Walkthrough

Adds a new Ampcode agent plugin implementing CLI detection, streaming JSONL parsing and runtime/setup/validation hooks; registers and re-exports the plugin. Also adds related docs, daemon guidance, error catalogue, repo metadata and session handoff logs.

Changes

Cohort / File(s) Summary
Ampcode Agent Plugin
src/plugins/agents/builtin/ampcode.ts
New TypeScript plugin AmpcodeAgentPlugin with CLI detection (which + --version timeout), runtime config and setup questions, argument builder (buildArgs), stdin handling, validation hooks, JSONL parsing helpers (parseJsonlLine, parseJsonlOutput) and a streaming parser factory (createStreamingJsonlParser). Exposes createAmpcodeAgent factory and default export.
Built-in Agents Index
src/plugins/agents/builtin/index.ts
Registers and re-exports Ampcode: imports createAmpcodeAgent, adds it to registerBuiltinAgents, and exports createAmpcodeAgent, AmpcodeJsonlMessage, and AmpcodeAgentPlugin.
Daemon message
.beads/daemon-error
New user-facing daemon error/help text for legacy Beads DBs describing migration steps and rationale for disabled auto-claiming.
Architecture / docs
.claude/cache/agents/scout/latest-output.md
New comprehensive architecture/design doc for the Ralph TUI agent loop orchestrator (sessions, plans, trackers, lifecycle, conventions).
Typecheck / repo metadata
.claude/tsc-cache/.../affected-repos.txt
Adds src entry to affected-repos list.
Error catalogue
.learnings/ERRORS.md
New error registry documenting four error scenarios with codes, contexts and remediation steps.
Session handoff logs
thoughts/shared/handoffs/events/*
thoughts/shared/handoffs/events/2026-01-14T21-39-32..., thoughts/shared/handoffs/events/2026-01-15T03-23-16...
Adds session-end handoff event files with timestamps and metadata.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant User as User (CLI)
  participant Agent as AmpcodeAgentPlugin
  participant CLI as amp binary
  participant Parser as Jsonl Parser

  rect rgba(200,230,255,0.5)
    User->>Agent: invoke agent (interactive / non-interactive)
    Agent->>Agent: detect `amp` (which + --version w/ timeout)
  end

  rect rgba(220,255,200,0.5)
    Agent->>CLI: spawn `amp` with built args (mode, flags, streaming)
    CLI-->>Agent: stdout (streaming JSONL / text)
    Agent->>Parser: push streaming chunks/lines
    Parser-->>Agent: parsed `AmpcodeJsonlMessage` events
    Agent->>User: stream parsed messages / final output
  end
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Poem

🐰 I hop through lines of JSONL bright,
I sniff the amp beneath the night,
I spawn the CLI and parse the stream,
Tiny messages dance and gleam,
Hooray — the Ampcode agent springs to light!

🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)
Check name Status Explanation Resolution
Out of Scope Changes check ⚠️ Warning Several changes are out of scope: documentation files (.claude/cache/, .learnings/ERRORS.md, thoughts/shared/handoffs/events/) are unrelated to implementing Ampcode agent support per issue #105. Remove documentation, error logs, and session files that are not part of the Ampcode agent implementation. Keep only ampcode.ts, index.ts updates, and .beads/daemon-error if directly supporting the feature.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely describes the main change: adding Ampcode agent support. It is specific, related to the primary objective, and follows conventional commit format.
Linked Issues check ✅ Passed The PR implements all coding requirements from issue #105: Ampcode agent plugin with CLI integration, non-interactive execute mode, --dangerously-allow-all flag, multiple agent modes, and JSONL streaming support for structured responses.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing touches
  • 📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Fix all issues with AI agents
In `@src/plugins/agents/builtin/ampcode.ts`:
- Around line 61-109: The plugin currently defaults dangerouslyAllowAll to true,
which is insecure; change the default value of the AmpcodeAgentPlugin instance
property dangerouslyAllowAll from true to false, and ensure the
initialize(config) logic still respects an explicit boolean
config.dangerouslyAllowAll to set it when provided; also update any other
occurrences of the same default (the second definition referenced around lines
198-231) to false so the opt-in behavior is consistent across the file.
- Around line 147-195: The runVersion function currently uses spawn(..., {
shell: true }) and a non-cleared setTimeout which risks shell injection/quoting
issues and event-loop leaks; replace spawn with child_process.execFile to run
the command directly without a shell (call execFile(command, ['--version'],
...)) and capture stdout/stderr from the callback, and store the timeout in a
variable so you can clearTimeout(timer) in both the error and close/finish paths
(or before resolving in the execFile callback) to ensure the timer is cleared
and the process resources are released; update any references to proc event
handlers to use the execFile callback error/stdout/stderr handling and resolve
with the same { success, version?, error? } shape.

@subsy
Copy link
Owner

subsy commented Jan 17, 2026

Thanks for this @carmandale

Im in the process of refactoring some of the code to improve the prompt templates, package them with tracker plugins and restructure the agent plugin paths. We also now have true built in sandboxing
Im going to get all that stuff live in a 0.2.0 release and then will need this PR to be refactored. It will also need tests to pass CI, and documentation.
You're welcome to take that on, or I can pick it up - lmk

Addresses CodeRabbit security feedback:
- Changed class property default from true to false
- Updated setup question default to false
- Added warning emoji to setup prompt
- Improved help text to clarify security implications

Users must now explicitly opt-in to autonomous mode.
@carmandale
Copy link
Contributor Author

Addressed CodeRabbit Security Feedback

Fixed the dangerouslyAllowAll security concern (same pattern as PR #118):

  1. Changed default from true to false - Users must now explicitly opt-in to autonomous mode
  2. Updated setup question default - Matches class property
  3. Added warning emoji and improved help text - Clarifies security implications

Commit: 9bb3069

Ready to rebase once 0.2.0 lands. Happy to add tests and docs as needed.

@codecov
Copy link

codecov bot commented Jan 18, 2026

Codecov Report

❌ Patch coverage is 10.76923% with 290 lines in your changes missing coverage. Please review.
✅ Project coverage is 45.04%. Comparing base (f9829c5) to head (f3057f8).
⚠️ Report is 101 commits behind head on main.

Files with missing lines Patch % Lines
src/plugins/agents/builtin/ampcode.ts 9.65% 290 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main     #120      +/-   ##
==========================================
+ Coverage   41.95%   45.04%   +3.08%     
==========================================
  Files          59       64       +5     
  Lines       12690    16312    +3622     
==========================================
+ Hits         5324     7347    +2023     
- Misses       7366     8965    +1599     
Files with missing lines Coverage Δ
src/plugins/agents/builtin/index.ts 87.50% <100.00%> (-12.50%) ⬇️
src/plugins/agents/builtin/ampcode.ts 9.65% <9.65%> (ø)

... and 42 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Fix all issues with AI agents
In @.learnings/ERRORS.md:
- Around line 15-16: The commit contains a personal/local filesystem path string
"Found JSONL file: /Users/dalecarman/Groove Jones Dropbox/Dale
Carman/Projects/dev/ralph-tui/.beads/issues.jsonl" in .learnings/ERRORS.md;
replace that exact path with a generic placeholder like "Found JSONL file:
/path/to/ralph-tui/.beads/issues.jsonl" (or sanitize programmatically where the
message is produced) and re-commit so no personal/local paths remain in the
repository.
- Line 84: Remove the personal filesystem path string "Ran in
/Users/dalecarman/Groove Jones Dropbox/Dale Carman/Projects/dev/ralph-tui" from
.learnings/ERRORS.md and replace it with a neutral placeholder (e.g., "Ran in
<project-path>" or simply remove the line); search the file for any other
occurrences of the same personal path and sanitize them the same way to avoid
leaking personal path information.
🧹 Nitpick comments (3)
.learnings/ERRORS.md (1)

1-122: Consider whether this file belongs in the repository.

This appears to be internal development notes documenting transient errors encountered during development. Such notes are typically kept outside version control or in a personal notes directory. If the intent is to document common errors for other contributors, consider:

  1. Moving to a more appropriate location (e.g., docs/troubleshooting.md)
  2. Generalising the content to be useful for all contributors rather than logging specific incidents
  3. Removing timestamps and incident-specific metadata

Additionally, this file appears unrelated to the Ampcode agent feature being added in this PR.

.claude/cache/agents/scout/latest-output.md (2)

232-232: Minor grammar: consider adding article.

Per static analysis, "highest impact" should read "the highest impact" for correct grammar.

Suggested fix
-- **Intelligent selection** - picks tasks with highest impact
+- **Intelligent selection** - picks tasks with the highest impact

507-510: Minor grammar improvements.

A couple of small grammar refinements for clarity.

Suggested fixes
-2. **What happens if you edit prd.json while session is running?**
-   - Tasks are loaded at session start into `trackerState.tasks[]`
-   - Mid-session edits probably won't be picked up until next session
+2. **What happens if you edit prd.json while the session is running?**
+   - Tasks are loaded at session start into `trackerState.tasks[]`
+   - Mid-session edits probably won't be picked up until the next session

Replaced personal filesystem paths with <project-root> placeholder
per CodeRabbit review feedback.
@carmandale
Copy link
Contributor Author

Fixed the personal path leak in .learnings/ERRORS.md per CodeRabbit feedback - replaced with <project-root> placeholders in commit 3e1f4e7.

Per CodeRabbit feedback:
- Replace spawn with execFile to avoid shell injection risks
- Properly clear timeout to prevent event-loop leaks
- Add resolved flag to prevent double-resolution
@carmandale
Copy link
Contributor Author

Fixed the spawnexecFile security issue per CodeRabbit feedback in commit f3057f8:

  • Replaced spawn(..., { shell: true }) with execFile to avoid shell injection risks
  • Added proper timeout cleanup with clearTimeout()
  • Added resolved flag to prevent double-resolution edge cases

@subsy
Copy link
Owner

subsy commented Jan 22, 2026

@carmandale do you want to try to refresh this PR to align with all the latest changes in the agent plugin system?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add Ampcode Agent Support

2 participants

Comments