npm / lalph
lalph
What changed in lalph 0.1 to 0.3, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-21.
14 breaking46 new APIs and options5 performance64 behavior and defaults3 tooling71 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initlalph 0.391 changes
Breaking changes 8
Open questions are now disallowed.
The Prd service no longer provides findById.
Custom review instructions now override the prompt completely.
Ralph worker startup now fails early with an actionable error when a project is missing ralphSpec.
Clanka model authentication is now required during preset setup.
Task estimates were removed from clanka.
chooseTask was removed from workers.
PR review feedback line numbers are now provided in a dedicated <lineNumber> XML tag instead of the comment attribute.
New APIs and options 18
Projects can select a Ralph agent preset, and Ralph mode uses the selected preset when running.
GitHub authentication now supports personal access tokens.
Adds IssueSource.findById for looking up an issue source by ID.
Exposes IssueSource.findById through a new task tool.
Adds a maximum context configuration for clanka.
Adds ralph loop mode.
Adds support for the clanka semantic search tool.
Adds a shared directory.
Adds support for websocket mode.
Adds an optional research agent.
Clanka runs can accept an optional steer stream and forward live task updates to the running agent.
Adds a proof-of-concept Clanka integration.
An optional GitHub project filter is available for project setup and issue syncing.
Plan flows prompt for an agent preset, allowing lalph plan and lalph plan tasks to use any configured preset instead of always using the default.
Adds --file (alias -f) to load plan content from a Markdown file and skip opening the interactive editor.
The Linear project selector can prompt for a project name and team, then create and select the new project.
Tasks are now set to in-progress using the API.
Agent presets allow different models to be used per task.
Performance 3
Task polling latency was improved.
The GitHub API client reuses cached responses for repeated GET calls when GitHub returns 304 Not Modified, reducing API rate limit usage.
The plan editor launches as fast as possible.
Behavior and default changes 27
GitHub PR feedback is injected in commit mode when the configured target branch has an open PR.
Project defaults were improved, which may affect developer decisions or configuration.
Ralph spec file selections are stored relative to the current project root.
After create, update, and cancel operations, cached issue state is mutated via SubscriptionRef.update instead of immediately re-fetching issues from the backing API.
Errors in scheduled refresh are now ignored.
Plan mode now uses clanka.
Websocket models are no longer memoized.
New temporary worktrees copy .lalph/shared instead of symlinking it, and sync the copy back to the main directory when the worktree is finalized.
The watcher now watches only for prd changes.
Tasks move to in-progress while the review agent runs, then return to in-review when review finishes.
The research prompt was tweaked; the notes do not specify how its behavior changed.
Task state watching is debounced.
A task branch is created before a worker starts.
Subagent reasoning was increased.
Setup output is now shown.
Eligible tasks are returned in priority order.
The output now shows each agent preset’s clanka model, helping developers see which model each preset uses.
The plan-mode agent preset is prompted for before creating or accessing the worktree.
Some fields may be omitted from prd.yml, or it can be created from strings only.
Outdated reviews are shown if they are not collapsed.
PR comments from common bot accounts are hidden.
Lookups prefer the current working directory, then fall back to the project root when running from subdirectories, aligning settings, cache, and worktree behavior.
Plan mode now commits and pushes generated specifications when it finishes.
Current issues are now uninterruptible.
Opencode thinking output is now shown.
The default issue description placeholder is blanked out when unchanged.
Active runs are canceled when the current task leaves in-progress or in-review.
Fixes and other changes 35
Prevents auto-merge tasks from becoming orphaned.
Claude CLI runs no longer swallow Ctrl-C; stdin is not inherited, and Claude is terminated with SIGINT, escalating to SIGKILL if needed.
Fixes gh schemas.
Fixed parseBranch.
Fixes branch parsing.
Plan mode presents only the path instead of the full text.
Use colored output in codex.
Restores the stall timeout for clanka.
Issue refresh is retried.
Fixed updates causing clanka steer messages.
Decoding PR data now accepts GitHub pull request review decision enum values.
Only external issue-source changes update .lalph/prd.yml, preventing internal refreshes from overwriting local edits.
Uses a sub ref for issues.findById.
The current issue state was improved.
Fixed the ralphDone flag.
The OpenAI provider was updated; the notes do not specify what changed.
Task-run cancellation now verifies task state against the issue source before cancelling a worker, fixing cancellation races.
Issues and plans are saved when a failure occurs.
GitHub label filters continue to apply when syncing issues through a selected project.
Non-issue GitHub project items are ignored when syncing issues from a selected project.
Tasks are marked as done when PR auto-merge succeeds in PR git flow.
Inserts
--before the prompt argument when using this option, preventing variadic tool parsing from swallowing the prompt and restoring chooser task selection.Preserves existing GitHub issue labels and applies only explicit label changes for workflow state and auto-merge labels.
Fixes the local worktree layer.
Diff hunks are wrapped with CDATA.
Dispose errors are ignored.
RunnerStalled errors are caught when the task has moved to in-review.
Unstaged working tree changes are cleared before commit-mode rebases, preventing post-work rebasing from failing on a dirty worktree.
Commit mode review now tries to ensure that changes are committed.
Issues are no longer created when nothing has changed.
Fixed the task chooser agent.
Fixed a race condition on task sync.
Fixes project editing.
Fixes project removal.
Fixes worker agents using preset args.
lalph 0.217 changes
New APIs and options 5
Plans can now be created in your configured editor.
Adds a checkout script.
Adds the --new flag to plan mode.
Command aliases were added.
Projects commands were added. Each project represents a sub-source of issues with its own configuration.
Performance 1
Launching the editor for the issue command is faster.
Behavior and default changes 6
PR feedback now includes review bodies.
Review prompt tweaks may affect review behavior.
Plan mode is improved.
The add wizard was improved.
Projects can be empty, and users are guided through first-time setup.
The project list now shows which projects are enabled.
Tooling 1
Commit flow instructions now require task references to be added in commits.
Fixes and other changes 4
Per-project key-value data is removed when its project is deleted.
Worktree setup fetches the target branch remote before checkout.
Failed runs always reset the task to todo.
Improves errors for chosen tasks.
lalph 0.195 changes
Breaking changes 6
An existing gitflow branch is force-deleted before checkout.
The opencode question tool is disabled.
Instruction generation was removed.
The AskUserQuestion tool is disabled to prevent hangs.
Switches to GitHub App OAuth.
The complete field was removed.
New APIs and options 23
Adds a dedicated source status command definition.
Adds support for custom review instructions.
Adds flagUnmergable to the git commit flow.
Adds a mode that does not create GitHub pull requests.
Agents now have spans.
Adds an option to enable the review agent.
Adds a reviewer agent.
Allows an added remote to target the branch setting.
Adds an option for verbose logging.
Adds -d as an alias for --dangerous.
Adds a flag to plan mode that skips permission prompts for supported agents.
Configure the editor used for issue creation and PRD editing; it falls back to EDITOR and then nano.
CLI commands can be prefixed to support Docker sandboxing.
Codex support was added.
Adds the --dangerously-skip-permissions option.
Adds a shell command.
Configuration can now be supplied using environment variables.
Plan mode now allows setting a target branch.
Implements two-way PRD sync.
The main run command gains a reset option.
Adds an option to reset the source before planning.
Adds a command to create an issue.
Adds opencode permissions.
Performance 1
Reduces Linear API calls.
Behavior and default changes 31
Created tasks inherit their parent task’s auto-merge setting.
The instructions prompt was improved, which may affect generated instructions.
The instruction prompt was improved, which may affect the behavior developers experience.
Adds logging of worker state, making worker state visible in logs.
The Claude output transformer was improved.
Linear issues are sorted.
Updates are allowed only for the chosen issue.
prd.yml is shared between worktrees.
The main loop now has a third step that generates the prompt for the main work agent.
The issue command now shows the created issue URL after it runs.
Uses --verbose for claude and formats the output.
Plan-mode prompts for review now include the specification text.
Specification review in plan mode now occurs in the final step.
Command prefix configuration is now a stored setting prompted by the agent selector.
PR detection details move into task selection, and existing PR numbers are passed into execution prompts.
Worktrees created without scripts/worktree-setup.sh are now seeded with one.
Empty blockedBy values are now emphasized.
The command prefix uses a string.
Completed projects are hidden.
The edit command's handling of existing worktrees changed.
The specs directory is now passed to the prompt.
The planner now receives the CLI agent environment.
The tool asks fewer questions.
Prompts were tweaked; the notes do not specify which prompts or how their behavior changed.
The worktree setup script path changed.
Plan mode now creates specs.
Context gathering receives more steering.
The system tries to record information as it is discovered.
The default maximum minutes value increases to 90.
The timeout prompt was tweaked.
Plan mode now asks for the idea in the agent.
Tooling 2
Tracing was added to currentIssuesAtom.
The CLI help text now mentions the default PR base branch, helping users understand which branch pull requests target by default.
Fixes and other changes 32
Retries auto-merge when merge conflicts occur.
When reading issues, stale values are no longer used.
Fixes the Linear integration’s handling of blockedBy.
Issue state may be reverted when a PR is missing.
Only open PRs should be re-used.
Descriptions now preserve spec info.
For the GitHub source, tasks are ensured to be in progress before another iteration starts.
Blocked-by lookups are skipped for Linear issues that are not todo.
In-progress issues are reset to todo before the root loop starts.
Plan reruns that regenerate tasks with missing IDs no longer create duplicate issues.
Claude work runs use stream-json output to avoid false stall detection.
PRD sync/update operations are guarded with a semaphore to preserve ordering.
Non-done updates now return to todo when an issue is reverted.
Fixes PR feedback output when only hidden review threads exist.
Improves the error message shown when a repository cannot be resolved during GitHub CLI repo discovery.
Uses the latest state for Prd updatedIssies.
Follow-up tasks from research work are instructed to depend on the research task.
PR lookup instructions are clarified, and task prompts use real newlines.
Task creation guidance now accounts for validation checks.
Logs no work when only one fiber exists—the current one.
Logs “no work” only when nothing is running.
Task reversion is improved.
Fixed cwd for some CLIs.
The CliAgent command model was updated.
Edit mode can now load without a worktree.
Fixes token managers not setting the current token.
The check for whether there is more work was improved.
The rebase instruction was adjusted.
The project tries to use the task description as a learning tool.
The “small task” wording was tweaked.
Tasks are broken up if they time out.
Fixed target branch checkout.