Best practices
In brief: Author requirements on-platform with ChimpHands, automate upkeep and fix-test workflows, and use ChimpHands chat or a local TestChimp-skilled agent when you need deeper interactive involvement.
ChimpHands is most effective when you play to its strengths: full repo context on CI, platform-linked entities, and async orchestration—while keeping interactive dev work on the tools you already use locally.
Author requirements with ChimpHands
User stories and scenarios are richer when the agent can read your actual codebase—APIs, folder layout, existing SmartTests, and policy files—not just a ticket title.
Recommended pattern:
- From Plans, create or select a story or scenario.
- Use Spec out with ChimpHands or the ChimpHands action menu (Scope out, Implement, Test) to hand off with entity context and optional line ranges pre-filled.
- Let ChimpHands run
author-plansor related workflows against the mapped branch.
The agent can infer acceptance criteria, edge cases, and traceability hooks that match how your app is structured. Review and edit the resulting markdown in Plans before implementation automations fire.
:::tip Context references Use the composer + menu to attach context without pasting ids:
| Kind | How |
|---|---|
| Platform entity | Story, Scenario, Issue, Test, Release, or Automation batch — searchable picker |
| Repo line range | Select lines in the diff/content pane → add as tag |
| Whole file | Drag from changed-files list, repo explorer, or attach path |
| Local upload | Upload local file — stored as artifact URL in the prompt |
/testchimp | Optional tag when you want the skill preamble in the message |
Tags serialize into the outbound prompt (ref: …, artifact URLs). Remove a tag before send if you change your mind. Details: Chat with platform and repo context.
:::
Collaborative editing during a session
When the CI runtime is healthy, use the file diff pane to review agent changes and edit files yourself—saves write back to the same worktree the agent uses. Prefer editing during pauses (agent waiting on you, or between turns) so you and the agent do not fight over the same file mid-tool-call.
Automate housekeeping workflows
Repetitive QA maintenance is ideal for ChimpHands + automations—predictable playbooks, clear success criteria, and low need for mid-run human steering.
Strong automation candidates:
| Workflow | Example trigger |
|---|---|
upkeep | Scheduled windowed aggregation or nightly cron-style event |
fix-test-execution | Test execution batch → failed |
instrument-truecoverage | Release → In Progress, or manual ChimpHands invoke after SDK merge |
fix-coverage-gaps | TrueCoverage insight threshold (via custom condition + task template) |
cleanup | Low-risk buffered window after large test imports |
Start with human approval before invoke or before plan execute until you trust the noise level, then loosen gates for overnight coverage. Prefer Buffered aggregation when many related events should collapse into one run (for example multiple failing tests from the same push).
Use ChimpHands as the invocation strategy so each run shares the same execution model as interactive sessions.
When to use interactive ChimpHands vs a local agent
| Situation | Prefer |
|---|---|
| Async fix after CI failure, release gate, or automation | ChimpHands (automation or fire-and-forget chat) |
| Clarifying questions mid-run on the same workflow | ChimpHands chat — join the live CI session |
| Authoring or refining requirements with repo context | ChimpHands from Plans |
| Pairing on app feature implementation in your IDE | Local agent (Cursor / Claude Code) with TestChimp skill |
| Experimenting with a new workflow playbook locally | Local agent — faster iteration, then promote to ChimpHands automations |
| Custom agent stack you already operate | Via GitHub Issue or Webhook — see Cloud agents |
Local agent setup: install the skill under .agents/skills/testchimp (or your host's skill path), commit mcp.json with npx @testchimp/cli@latest mcp, and export TESTCHIMP_API_KEY. That wiring is required for local and BYO cloud agents—ChimpHands on CI installs skill + CLI automatically; you only need the GitHub Actions secret at project setup.
For provider-specific listener configuration (Cursor Cloud, Claude Code Action, Codex, Copilot), see Setting up cloud agents—that page covers bring-your-own agents, not ChimpHands itself.
Operational tips
- Keep the ChimpHands workflow on the default branch — automations dispatch against the installed
chimphands.yml. - Grant Workflows write on the GitHub App when ChimpHands needs to update workflow files; the job prefers a short-lived App installation token for git operations.
- Set
TESTCHIMP_BACKEND_URLin GitHub Actions variables when the project targets staging or enterprise—not only production. - Monitor Workflow Executions — tune task templates and conditions if runs are too chatty or miss events.
- Watch ChimpHands credits — align automation breadth with your QA budget; see Why ChimpHands.
Related
FAQ
When should I use ChimpHands vs a local agent?
ChimpHands for async QA, automations, and repo-context plan authoring from Plans. Local Cursor or Claude with the TestChimp skill for heavy IDE pair-programming on features.
Which workflows should I automate with ChimpHands?
upkeep, fix-test-execution, instrument-truecoverage, fix-coverage-gaps, and cleanup are strong candidates—often with Buffered or Windowed aggregation and optional human gates.
How do I author requirements with ChimpHands?
From Plans use Spec out with ChimpHands or the action menu to hand off stories and scenarios with entity context; the agent runs author-plans against your mapped branch.
What GitHub permissions does ChimpHands need?
TestChimp GitHub App with repo access; Workflows write when the agent must update workflow files. TESTCHIMP_API_KEY in Actions secrets; optional TESTCHIMP_BACKEND_URL for non-prod.