Frequently asked questions

What should I try first?

Pick a small bug or improvement in a project you know. Follow Start here to install Shaka, ask the agent to configure the repository, and run your task. Working with Shaka explains the PR you get and your merge decision.

Do I need to write configuration by hand?

No. Ask the skill to inspect your project and reuse its existing checks. For shared setup, review the agent's choices and merge the initial setup PR yourself. See repository setup.

Can I try it without changing team configuration?

Yes, if the repository has no shared Shaka settings:

$shaka <task or issue link>
Set up Shaka just for me. Go.

Settings stay out of commits. See individual support and acceptance gaps. With team settings, local choices do not override them. You can explicitly select a settings PR for one task. Trying a different Shaka implementation is separate: see try a Shaka PR.

Can I use a different setting than my team?

For one task, say it in your request, such as Use Ask for this task, where the setting allows it. For a lasting change, propose a settings PR and select it for your tasks until it merges.

Individual settings do not apply in a repository with team settings, even for a value the team leaves out: Shaka uses its own default there. Settings always come from one source, so you can tell which choices governed a task. See which settings apply.

Why did the agent stop to ask about model and effort?

Before it changes code, Shaka recommends a model and effort for the task. “Go” without naming either accepts your agent's current settings, even when they differ from the recommendation or cannot be reported. If you name either setting, Shaka pauses when the settings are unavailable, unverified, or differ from its recommendation. See give it an outcome.

Why didn't the agent merge my PR?

Under Ask, the default, the agent labels the PR awaiting-merge-approval and names the commit to merge. Merge it on GitHub, or approve that commit and the agent merges it. Under Auto, a PR past the size limits, or one that changes trust, authentication, releases, or other consequential areas, still comes back to you. See choose a merge policy.

Can I make sure the agent never merges?

Under Ask, the agent merges only after you approve that PR's commit. To have a task end at the PR, say so in your prompt, for example Open a PR and stop. Ask relies on the agent following its instructions, and the agent acts with your GitHub permissions. To have GitHub block the merge, protect the base branch: require an approving review, and give no bypass to administrators or to any role, team, or app that includes your account. The agent opens PRs as you, so someone else then has to approve each one. An administrator can still change these rules, so the block holds only when the agent's account is not an administrator.

Does a green review job mean the PR was reviewed?

No. A job can pass without producing a review. The agent reads the report and counts only one that covers the current commit. See review.ci_review_jobs.

Can the agent review its own work?

It prefers a reviewer from a different provider, in the order set by review.local_review_agents. Next it uses a listed reviewer from the same provider. When no listed reviewer is available, a fresh session with the implementation model reviews the change without the implementation conversation.

Why does Shaka use a separate review session?

A fresh session reviews without the implementation conversation. This supplies another perspective, without guaranteeing quality. Shaka uses a restricted CLI or its supported API adapter and records the reviewed commit, findings, and available usage. It does not count a same-host subagent as the local review.

Reviewers have different access to unchanged code. See reviewer choices and limits and what Shaka enforces.

Do multiple reviews run one after another?

The agent runs them concurrently and combines their findings before repairs. Additional reviewers add cost and may increase elapsed time. See reviewer count.

Why did the agent ignore a PR comment?

Shaka trusts the people who maintain the project: anyone with write access, plus the users, bots, and teams listed in .agents/shaka/trusted-github-actors.yml or your machine's allowlist. On a public repository, anyone else can comment, and that text could try to steer the agent. The agent withholds those comments and keeps their links for you to read. To change the allowlist, ask:

$shaka Add USER to this project's trusted GitHub actors.

Where is Shaka installed, and is that my configuration?

New installs put the Shaka source in ~/.local/share/shaka/source. That checkout is not configuration, and you never edit it. Your settings live in each project's .agents/shaka/ folder and in ~/.agents/trusted-github-actors.yml.

Older installs used ~/.agents/shaka, which looked like settings. The installer now refuses that location and prints one command that clones Shaka into the new default and moves your skill links there. Run it, then delete the old checkout. If the new default already holds something else, the message says what to move aside first. install --status names the same command.

Where do I put project rules?

What	Where
Commands, merge policy, and review jobs	Settings in .agents/shaka/config.yml
Project constraints, review criteria, and writing style	AGENTS.md
What the local reviewer looks for and how it reports	review.replacement_prompt_file, replacing Shaka's defaults
Changes to Shaka's workflow	A fork of Shaka

Shaka reads AGENTS.md from Git at the trusted commit. When AGENTS.md is a symlink to another file in the repository, such as CLAUDE.md, Shaka reads that file at the same commit. Claude Code is a separate case: recent versions can read AGENTS.md directly, but not in every session, and not by default when a CLAUDE.md exists. To give Claude the same instructions every time, add a CLAUDE.md containing @AGENTS.md. See Claude Code's AGENTS.md support.

Can I customize the prompt Shaka gives its local reviewer?

Yes. Write your own rules in .agents/shaka/instructions/review.md. Shaka adds them after its default instructions, so you keep Shaka's rules and add yours; review.custom_instructions_file names another file. To remove one of Shaka's rules instead, set review.replacement_prompt_file to a copy of the default instructions, or set replacement_prompt_file on one agent's entry in local_review_agents. Paths are relative to the repository root.

With shared settings, Shaka reads the default-branch version, so a PR that edits it is reviewed with the current version. With individual setup, keep the file in .agents/shaka/, where it stays out of commits. Criteria in AGENTS.md still apply on top of the prompt file. The prompt file configures local reviews; a CI review job takes its prompt from its own workflow.

The settings reference explains which instructions apply and links the review protocol.

Can a PR change Shaka's settings or rules for itself?

Editing settings in a PR does not select them automatically. Shared settings and review criteria normally come from the default branch. A maintainer can explicitly select a settings PR's pinned configuration for experiments. A fork PR cannot choose its own review rules. See which settings apply.

What is a checkpoint?

It helps the task owner choose what to do next. See the checkpoint guide for its terms, how it differs from the code walkthrough, and current report labels.

Can I hide my checkout path while keeping the chat locator?

Yes. Set wip.include_checkout_path: false. WIP Details then show REDACTED for the checkout path and keep the chat locator, which helps resume the owning chat. See WIP settings.

What does Shaka enforce, and what relies on the agent?

Ruby checks settings and trusted comment authors. When the agent merges, it also checks the reviewed commit and, when review is required, that posted review covers it or that a reason for skipping review was given. How thorough that review was, test quality, screenshots, and privacy rely on the agent's judgment. See what is enforced.