Use the terminal as an operating surface, not the plan
A terminal agent can inspect files, edit code, and run commands, but those capabilities do not decide what should change or what evidence is enough.
Terminal coding agents put repository search, file edits, builds, and tests in one conversational loop. OpenAI documents interactive and non-interactive Codex CLI modes, while Anthropic documents permission modes, turn limits, and resumable Claude Code sessions. The interfaces differ, but the engineering job is the same: give the agent a bounded outcome, let it use the tools needed for that outcome, and keep consequential commands visible.
Do not treat shell access as blanket permission. Package installation, network access, process management, migration commands, and destructive Git operations can change more than the requested code. Keep the normal read-edit-test loop inside the agreed workspace and stop when completion needs credentials, production access, destructive action, or a new product decision.
Start from an explicit repository state
Before the first edit, confirm the repository path, branch, current changes, and the exact behavior the task should produce.
A good terminal session begins with orientation. Check the current directory, inspect the branch and working tree, and note whether existing edits belong to someone else. A dirty tree is not automatically a blocker, but it changes the contract: the agent must preserve unrelated work and distinguish its own diff during review.
Then state the outcome in behavior terms. “Improve the login code” leaves scope and proof open. “After a session refresh, return a signed-in user to the safe local page they requested” identifies an observable result and a boundary without prescribing an implementation. Brief's setup check can confirm the local repository and route the request to a compact context packet or a larger mission before edits begin.
- Repository root and current branch
- Existing staged, unstaged, and untracked work
- Observable outcome and explicit non-goals
- Commands or external actions that require new authority
Search for the local contract before editing
The first useful commands locate the governing rules, closest implementation, affected tests, and runtime path—not every file that mentions the feature.
Start with the repository's entry guidance and narrow searches for the route, symbol, error, or user-facing string named by the task. Read the closest working implementation before creating a helper or pattern. Find the test that defines neighboring behavior and the package command that runs it. This creates a small working set that can change the plan.
Command output is context, so keep it deliberate. A huge log or broad recursive dump can hide the one failing assertion that matters. Prefer a narrow search, a bounded file range, and a focused test. If the first inspection reveals an authentication, tenant, data, deployment, or ownership boundary, refresh the plan before touching it.
Give the terminal session a task contract
A compact contract tells the agent what it owns, what it must preserve, how to prove the result, and when to stop.
The contract can be plain language. It should name the outcome, likely scope, non-goals, reusable patterns to prefer, focused validation, and actions outside the agent's authority. That is enough freedom for normal searches, edits, and tests without turning every command into a permission discussion.
Keep implementation details provisional until the repository supports them. Naming a file can help routing, but ordering the agent to add a new abstraction before it inspects nearby code can lock in the wrong plan. Ask for the smallest coherent change and require the agent to report when evidence expands the scope.
| Contract field | Example | Why it matters |
|---|---|---|
| Outcome | Preserve a safe local return URL after session refresh. | Makes the result observable. |
| Boundary | Keep provider configuration and unrelated navigation out of scope. | Limits authority and diff growth. |
| Proof | Run the focused session tests and review the final diff. | Defines evidence before implementation. |
| Stop | Ask if the redirect policy or production credentials are required. | Keeps new decisions with their owner. |
Edit and test in short, inspectable loops
After each coherent change, inspect the affected diff and run the narrowest check that can expose the next wrong assumption.
The agent should be able to search, edit, run a formatter or focused test, diagnose a failure, and revise without waiting for approval after every reversible step. Short loops keep failures close to their cause. They also make it easier to notice when a small request is turning into a cross-package refactor.
Review commands before they run when the tool asks for approval. Prefer the least access that can complete the task, and do not bypass sandbox or permission controls merely to make the session quieter. A failed test is useful evidence: determine whether it points to a narrow defect, a stale assumption, or an unrelated baseline failure, then update the corresponding stage of the plan.
End with the diff, exact checks, and remaining risk
A terminal transcript shows activity; a useful handoff identifies the changed behavior and the evidence that supports it.
Before calling the task done, inspect the final working tree and diff. Run the focused tests again from the state being handed off, then add broader checks only when the change justifies them. Record commands and results exactly, including failures and skips. If a browser, runtime, or integration behavior was not exercised, keep that gap visible.
Brief can review the local diff against the task, available pre-coding context, repository rules, secrets, and validation evidence. That review is not a substitute for product judgment or an approval to merge. The final handoff should let a reviewer see what changed, what passed, what remains uncertain, and which decision still belongs to a person.
- Inspect the final branch and working-tree state.
- Read the complete task diff, including tests and configuration.
- Run the narrow checks that prove the requested behavior.
- Record broader checks that passed, failed, or were skipped.
- Report remaining risk and any action that still needs approval.
Common questions
Questions worth asking next
What should I include in a terminal coding-agent prompt?
Include the observable outcome, repository or feature in scope, important non-goals, the proof you expect, and actions that require approval. Let the agent inspect the code before fixing exact files or abstractions in the plan.
Is a terminal AI coding agent safe to run with automatic approvals?
Automatic approval changes how commands are authorized; it does not make every command safe. Use the narrowest sandbox and permission policy that supports the task, keep destructive and external actions explicit, and inspect the final diff and validation evidence.
Is a terminal workflow different from an IDE agent workflow?
The interface is different, but the core loop is the same: define the outcome, gather repository evidence, bound authority, change, verify, and hand off. Terminal sessions make command scope and working-directory state especially important.