How to run your AI assistant in the terminal, where it can see your actual files

Type the command on its own and you get an interactive session. Add a flag and you get one answer and your prompt back. Almost everything in this article is one of those two.

Inside an interactive session, one habit is worth adopting immediately: you can run a shell command yourself without leaving, by starting the line with an exclamation mark. The output lands in the conversation, so the assistant sees exactly what you saw. It beats running the command in another window and pasting a summary of what you think happened.

Same as any other command line tool. Anything that writes to your screen can be fed to it instead.

git log --oneline -8 | claude -p "Summarize these commits in one sentence."

That returned one accurate sentence describing eight commits, which is a small thing that turns out to be useful constantly. The same shape covers most of what people want from this: a log file in, a plain-English explanation out.

• Feed it a failing test run and ask which change most likely caused it.
• Feed it a diff and ask what a reviewer would flag.
• Feed it a wall of server logs and ask for the three distinct errors hiding in the repetition.
• Feed it a CSV and ask what’s wrong with the data before you import it.

The gotcha that will get you once: run it with no pipe and it sits there waiting for input, then warns you it gave up waiting. If your command isn’t piping anything in, end the line with < /dev/null and it starts instantly.

More than you’d guess, and for a reason worth understanding, because it changes how you use the thing.

Ask for the machine-readable output and it reports what the call weighed.

git log --oneline -8 | claude -p "Summarize these commits." --output-format json

On that run the prompt itself measured two input tokens. The context loaded around it measured 16,796. Your question is a rounding error. What you’re paying for is the assistant’s system instructions, your project instructions, your saved preferences, and the definitions of every tool it might reach for, all of it assembled fresh for a call that lasted four seconds.

Which means the lever isn’t your prompt length. It’s which model you sent it to.

Be honest about what that column means. On a subscription plan you are not billed per call, and the number the tool reports is an API-equivalent figure. It’s still the right way to compare two approaches, and if you ever put one of these in a loop or a cron job it becomes a real number very quickly.

Summarizing a log does not need your best model. Reserve the expensive one for work where judgment is the product.

Limit what it’s allowed to touch. You can hand it a list of permitted tools, and anything outside that list simply isn’t available, so a read-only question stays read-only no matter how the conversation goes.

claude -p "How many articles are in lib/resources and what are their slugs?" \
  --allowedTools "Read Grep Glob" < /dev/null

It found the files, listed them, and volunteered that two of them existed on disk but weren’t wired into the index yet. Which was true, and was the thing I would have shipped without noticing. That is the whole argument for the terminal in one example: it answered a question about the code by reading the code.

Beyond the allow-list, three habits carry the rest of the risk.

1. 01Commit before you turn it loose. Not because it’s reckless, but because “undo the last twenty minutes” should always be one command away.
2. 02Say what to verify, not just what to do. “Run the build and show me the output” gets you evidence. “Fix the build” gets you a claim.
3. 03Kill a session that’s gone sideways instead of arguing with it. Whatever you’ve spent is spent, and starting clean with a better first message is almost always faster than steering.

That second one matters more than it sounds. An edit applying cleanly is not the same as the thing working, and the gap between those two is where most bad afternoons come from. It’s also the slot people most often leave out of a request: say up front how you’ll know it worked.

Anything you’d otherwise retype. Drop a markdown file in the project root and your assistant reads it every time it works in that folder. In Claude Code that file is CLAUDE.md; most terminal assistants have an equivalent, so check yours.

Keep it short and keep it specific to this project. General good practice is already known; what it can’t guess is your particulars.

# Working in this repo

- Package manager is pnpm. Never npm.
- Dev server: pnpm dev on port 3000. Stop it before running a build,
  a build against a live dev server corrupts the cache.
- Content lives in lib/resources as one file per article. Adding one
  means writing the file and adding it to the index. Nothing else.
- Never hardcode a count in copy. The lists grow.
- No em-dashes anywhere in published copy.

Every line in there is a mistake somebody already made once. That’s the test for whether a line belongs: it earns its place by having cost you something.

Hooks. Your settings file can run a command at certain moments, and the output goes into the conversation. The most useful one by far runs when a session starts, so the assistant opens already knowing the state of things.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "bash ~/scripts/check-project-rules.sh" }
        ]
      }
    ]
  }
}

Ours checks whether our shared conventions file has drifted out of date and prints a warning if it has. Other good candidates: uncommitted work sitting in a repo you thought was clean, a list of tasks waiting for you, whether a deploy is ahead of what’s committed.

The rule for hooks is that they should tell you something you’d otherwise find out too late. A hook that prints something you already know is just noise at the top of every session, and you’ll start skipping past it, including the day it says something important.

1. 01Batch your feedback. Walk the whole page or the whole file, write down all twelve things, hand over all twelve at once. Twelve separate asks cost far more than one list of twelve, in money and in your attention.
2. 02Pick the model for the job. A log summary, a rename, a formatting pass: none of those need your best model, and the cost difference is real.
3. 03Use the exclamation prefix. Run the command in the session so the output is in the conversation, instead of describing what you saw in another window.
4. 04Commit small and commit often. Your undo button only works if you made one.
5. 05Ask for the evidence. “Show me the output” and “screenshot it and look at it” are the two phrases that separate work that’s done from work that’s reported as done.
6. 06Start fresh when the thread gets long. A new session with everything you’ve learned in the first message beats a tired one with forty turns of dead ends in it.

None of that is complicated. It’s just the difference between a tool you use and a tool that works.

You don’t need to be a developer, but you do need to be genuinely okay in a terminal: running commands, reading an error, knowing which folder you’re standing in. If typing a command makes you nervous, the chat window is a completely reasonable place to stay, and everything about writing a good prompt still applies there.

Scripted calls add up in a way interactive sessions don’t feel like they do. One call is a few cents of API-equivalent weight. The same call in a loop over two hundred files is a real number, and the harness context gets rebuilt every single time. Measure one before you write the loop.

There is usually a stripped-down mode that skips loading all that context, and it’s worth knowing that it typically expects an API key rather than the login you use interactively. We tried it on an ordinary signed-in setup and it failed immediately. Test that path before you build a script around it.

And don’t automate anything destructive. Read-only sweeps, summaries and drafts are excellent unattended. Deletes, deploys, and anything that touches production want a human looking at the screen.

Every command and number here was run on Claude Code 2.1.228 on macOS in August 2026, one run each rather than an average. CLI flags change faster than almost anything else in this space, so check your tool’s current help output before you rely on a flag.