How to Start Using a Terminal Coding Agent: Setup, First Tasks and Guardrails

A terminal coding agent is a command-line program that reads your repository, edits files and runs commands to complete a task you describe. This manual covers the first week: getting one installed, running a first session without surprises, and the habits that make the difference between an agent that saves time and one that creates review work. It applies to any of the agents in the terminal coding agent ranking.

Before you install

You need three things:

• A git repository with a clean working tree. Git is your undo button. Commit or stash your own changes first so that everything the agent does shows up as a diff you can inspect and revert.
• A runtime for the agent. Most terminal agents are distributed through npm (which needs Node.js), some through PyPI (Python) or Homebrew, and several ship a standalone installer.
• Access to a model. Either a subscription from the agent's vendor or an API key from a model provider. Open-source agents generally take any key; vendor agents are usually tied to their own models.

Installing

These are the six most downloaded terminal agents this week, with the install commands for the packages we track. Vendors sometimes recommend their own installer instead, so check the linked documentation.

After installing, run the agent from the root of your repository. On first launch it will ask you to sign in or provide an API key.

Your first session

Do not start with a feature. Start with three steps that build trust in order:

1. Ask a question it can only answer by reading. For example: "Explain how a request gets from the router to the database in this project, with file names." Nothing is changed, and you learn how well the agent navigates your code.
2. Ask for a small change with an obvious check. A bug with a failing test is ideal: "The test test_rounding fails. Find out why and fix it; do not change the test." Watch which files it opens and which commands it runs.
3. Review the diff as you would a colleague's. Run git diff, read all of it, and run the tests yourself. If it is right, commit. If not, say what is wrong and let it try again, or git checkout . and start over with a clearer request.

An agent is fast at producing changes, so your review is the limiting step. Keep tasks small enough that you can read every line of the result.

Write down what the agent should know

Agents start each session knowing nothing about your project. Most of them read a Markdown file of standing instructions from the repository root: AGENTS.md is the common convention across tools, and some agents use their own file name (Claude Code reads CLAUDE.md). Put in it what a new team member would need on day one:

• How to install dependencies, run the tests and run the linter, as exact commands.
• The layout of the repository in a few lines.
• Conventions that are not obvious from the code: naming, error handling, what not to touch.
• Things the agent has got wrong before. When you correct the same mistake twice, add a line.

Keep it short and specific. A page of concrete commands beats ten pages of principles.

Permissions: start strict

Every terminal agent has a setting for what it may do without asking. The usual levels are: ask before each edit and each command; edit freely but ask before commands; or run without asking.

• Start with approvals on. Reading the commands an agent proposes is how you learn where it is reliable.
• Allow safe, repetitive commands such as your test runner once you trust them, and keep approval for anything that deletes, installs, pushes or touches the network.
• Use a sandbox or container for unattended runs. If you let an agent run without approvals, do it where a mistake cannot reach your credentials or production systems.
• Be careful with untrusted content. An agent that reads a web page, an issue or a dependency's README can be given instructions hidden in that text. Do not combine "reads untrusted input" with "can run anything without asking".
• Keep secrets out of reach. Do not paste credentials into a session, and exclude files such as .env where the agent supports it.

Habits that pay off

• Say what done looks like. "Add input validation to the signup form; the existing tests must pass and add tests for the three invalid cases" produces better work than "improve the signup form".
• Ask for a plan first on anything large. Have the agent outline the steps and the files it will touch, correct the plan, then let it implement.
• Paste the evidence. Error messages, stack traces and failing test output are the best context you can give.
• One task per session. Long sessions fill the agent's context with stale detail and get slower, costlier and less accurate. Start a fresh session for a new task.
• Commit often, on a branch. Small commits make it cheap to throw away a wrong turn.
• Stop a loop early. If the agent tries the same failing fix three times, interrupt it, add information it lacks, or do that step yourself.

Keeping cost under control

There are two billing models, and they behave differently:

• Subscription with a usage allowance. You will not get a surprise bill, but you can hit the limit mid-task. Larger models and long sessions use the allowance faster.
• API key, billed per token. There is no ceiling unless you set one. Set a spending limit with your model provider before the first session, and check usage after a typical day to learn your own rate.

In both cases the main drivers are the size of the model, how much of the repository the agent reads, and how long a session runs. Clear instructions and small tasks reduce all three.

Using an agent in automation

Most terminal agents have a non-interactive mode that takes a prompt, runs to completion and exits, which makes them usable in scripts and CI: triaging a failing build, drafting release notes, proposing a fix as a pull request. Treat this as a second step, after you know how the agent behaves interactively on your codebase, and give the job the narrowest permissions and credentials that let it do its work.

Choosing which one to start with

If you already pay for a vendor's assistant, start with the agent that subscription includes. If you want to choose your own model, start with one of the open-source coding agents. Either way, the live numbers on each agent's page show how widely it is used, how recently it was updated and what it costs:

#	Agent	Pulse	Downloads 7d	7d	30d	Stars	Latest release	Last 90 days
1	OpenAI CodexOpenAI	82	25.6M	▲up 5.7%	▲up 21.2%	128K+153/day	0.160.1yesterday
3	Claude CodeAnthropic	80	14.8M	▲up 11.6%	▼down 36.4%	150K+161/day	2.1.290yesterday
5	PiEarendil Inc. (created by Mario Zechner)	75	5.2M	▲up 29.8%	▲up 52.1%	113K+378/day	1.0.4yesterday
7	OpenCodeAnomaly (SST team)	73	3.3M	▲up 22.0%	▲up 6.1%	212K+200/day	1.18.346d ago
24	Gemini CLIGoogle	57	453K	▲up 4.7%	▲up 1.8%	107K+24/day	0.62.07d ago
26	Oh My PiStencil Labs (Can Bölük)	56	241K	▲up 11.4%	▲up 53.9%	34.4K+111/day	18.6.12d ago
34	ClineCline Bot Inc.	52	95K	▲up 10.1%	▼down 37.2%	69.9K+63/day	0.0.434d ago
40	OpenHandsOpenHands (formerly All Hands AI)	50	316K	—	—	90.1K+98/day	1.25.0today