A practical guide to your terminal configuration for Claude Code

Claude Code works without custom terminal settings. Configure it when you need clearer permissions, reusable project guidance, working shortcuts, or hooks for a specific task. This guide covers those choices and a terminal workflow for reviewing an eesel support teammate.

What is Claude Code?

In a nutshell, Claude Code is an AI coding assistant from Anthropic that works inside your command-line interface (CLI). Instead of chatting with an AI in your browser, you have a "pair programmer" that can actually read your project files, understand the context of your codebase, write new code, and even run shell commands to test things or manage your git repo.

It's called an "agent" because it can string together a series of actions to complete a bigger task. You can ask it to plan a new feature, write the code across multiple files, and then package it all up in a pull request. This tight integration with your local environment is what makes it so specialized for development work.

The foundations of your terminal configuration for Claude Code

Start with two kinds of configuration. settings.json controls technical behavior such as permissions and hooks. CLAUDE.md gives Claude Code instructions about the project. They solve different problems, and both belong in a dependable setup.

Configuring your settings.json files

Use settings.json to control permissions, hooks, and a default model. Settings have a clear order of precedence, from highest to lowest: organization-managed settings, command-line choices, local project settings, shared project settings, and user settings.

• User settings ("~/.claude/settings.json"): This is your personal default file. The settings here apply to every project you work on.

• Project settings (".claude/settings.json"): This one lives in your project folder and should be checked into version control so the whole team is on the same page. It’s perfect for project-wide rules, like telling Claude to keep its hands off your ".env" files.

• Local project settings (".claude/settings.local.json"): This is for your own personal tweaks on a project that you don't need to share with the team.

Here is a valid shared-project example. It auto-approves edits under src/, git status, git diff, and the project test command. It blocks reads of common environment files at the project root. It does not promise to restrict all reads to src/; add separate deny rules for any other sensitive paths in your project.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Edit(/src/**)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(pnpm test *)"
    ],
    "deny": [
      "Read(/.env)",
      "Read(/.env.*)",
      "Bash(rm *)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/format-typescript.sh\""
          }
        ]
      }
    ]
  }
}

Put this script in .claude/hooks/format-typescript.sh and make it executable. It requires jq to read the event JSON from standard input. It also assumes Prettier is installed and pinned in this project’s devDependencies, so pnpm exec prettier uses the lockfile version rather than downloading a formatter on demand. The command uses CLAUDE_PROJECT_DIR, so it still finds the script if the session changes directories. The script gets the path from .tool_input.file_path rather than from an undefined shell variable.

#!/usr/bin/env bash
set -euo pipefail

file_path="$(jq -r '.tool_input.file_path // empty')"
cd "$CLAUDE_PROJECT_DIR"
case "$file_path" in
  *.ts|*.tsx) pnpm exec prettier --write "$file_path" ;;
  *) exit 0 ;;
esac

Write|Edit matches tool names, not filenames. The script filters the extension after the tool runs and selects the project's installed formatter. A PostToolUse hook cannot prevent the original write. In project settings, the leading slash anchors these patterns to the session's primary working directory, not the filesystem root or the .claude directory. Read/Edit rules do not block arbitrary subprocesses from opening files indirectly: use sandboxing for an operating-system boundary. The sonnet alias follows the provider's current mapping; ANTHROPIC_MODEL or --model can override the session choice, subject to organization policy. See the official permissions, hooks, and model settings references.

Providing context with CLAUDE.md files

The "CLAUDE.md" file is a bit different. It’s not for technical settings; it’s a Markdown file that Claude reads every time it starts up in your project. Think of it as a cheat sheet or a persistent set of instructions for the AI.

You can use it to tell Claude about:

• Coding standards: "We use TypeScript for all new code. Please follow the ESLint rules."

• Project architecture: "Just a heads-up, the frontend is Next.js and the backend is Node.js with Express."

• How to run tests: "New tests go in Jest. You can run them with pnpm test."

• Common commands: A quick list of build or test commands so it doesn't have to guess.

Here’s a snippet of what one might look like:

# Project Context for MyWebApp

## Coding Standards

- All new components should be functional components using React Hooks.

- We use `pnpm` for package management, so please don't use `npm` or `yarn`.

- Write unit tests for all new utility functions you add to the `src/utils` directory.

## Key Files

- The main entry point is `@./src/index.tsx`.

- Global styles live in `@./src/styles/global.css`.

- API calls are all handled by functions in `@./src/lib/api.ts`.

Advanced customization for your terminal configuration

Once you have your foundational setup dialled in, you can explore some of Claude Code's more advanced features. This is where you can build some really powerful shortcuts and automate the repetitive parts of your day.

Extending capabilities with MCP servers and hooks

Model Context Protocol (MCP) is a fancy name for letting Claude Code connect to external tools. You could set up an MCP server to let Claude query a database, pull information from Figma, or run a security scanner. It’s incredibly powerful but, fair warning, it does require some technical legwork to set up and maintain.

This older screenshot illustrates a documentation query, not the current hooks browser or a verified hook run.

Hooks run code at defined points in a Claude Code session. Use a PostToolUse hook for follow-up work such as formatting or a targeted test after an edit. Use a PreToolUse hook when the goal is to inspect or block an action before it runs. Keep hooks small and predictable: a failing formatter should not become a mystery during every edit.

One practical extension is the eesel CLI. Claude Code can run it to operate an eesel AI support agent: inspect connected sources, update its knowledge, and test answers. It operates the same eesel agent and workspace shown in the eesel dashboard, so the support team can review the configuration there.

Creating reusable slash commands with skills

If you repeat a detailed prompt, make it a skill. For a project-wide /review-pr command, create .claude/skills/review-pr/SKILL.md; for a personal one, use ~/.claude/skills/review-pr/SKILL.md. The skill can hold the review checklist, the project conventions, and any allowed tools in one reusable place. Files in .claude/commands/ still work for older setups, but skills are the recommended format for new commands.

Best practices and common challenges

Getting the most out of Claude Code isn't just about config files. It’s also about your environment and understanding what the tool can't do.

Choosing the right terminal

See Reddit users' thought: what is the best terminal for claude code?

Reddit

Claude Code works in any terminal without special configuration. Pick the terminal that fits your operating system and workflow; the useful configuration is about input, notifications, and multiplexers, not a universal performance ranking.

| Terminal | Key Feature | Best For | Platform | | :--- | :--- | :--- | | iTerm2 | macOS notifications and Option-key controls | macOS users who want a graphical terminal configuration | macOS | | Windows Terminal | Shift+Enter works without setup | Windows users | Windows | | Ghostty or Kitty | Desktop notifications without extra setup | Users who prefer one of these terminal interfaces | macOS, Linux |

For multiline input, Ctrl+J and backslash followed by Enter work in every terminal. Shift+Enter works without setup in many terminals, including iTerm2, Warp, Windows Terminal, and Kitty. In VS Code, Cursor, Devin Desktop, Alacritty, and Zed, run the built-in /terminal-setup command once. If you use tmux, the layer between Claude Code and the outer terminal, add the documented passthrough and extended-key settings to ~/.tmux.conf; without them, tmux can hide notifications and Shift+Enter.

This is a historical npm installation example. For a new installation, follow Anthropic's current native-install quickstart.

Configure Claude Code to work with an eesel teammate

Your project CLAUDE.md guides the coding session. The eesel teammate's standing instructions guide its support work. Keep that distinction clear when asking Claude Code to help with a rollout: a local coding rule does not automatically become the support agent's policy.

eesel CLI operates the same agent and workspace as the dashboard. Use it to inspect the teammate's existing instructions before making changes, and let the support team review that configuration in the interface they use.

With Node.js 18.17 or newer, start with an existing workspace:

npx @eesel/cli login
npx @eesel/cli whoami
npx @eesel/cli agents

Stop if whoami names the wrong account or workspace. In CI, EESEL_API_URL and EESEL_API_TOKEN take precedence over stored login credentials. If the workspace has several agents, use --agent on every command that reads or changes an agent. Otherwise the CLI can use the default selected earlier with eesel agents use <agent>, which may not be the agent you mean to inspect.

TARGET_EESEL_AGENT="REPLACE_WITH_OWNER_APPROVED_TEAMMATE"
npx @eesel/cli status --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli integrations download list --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli instructions --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli activity --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli approvals --agent "$TARGET_EESEL_AGENT"

The commands return JSON, so Claude Code can inspect their results as it works. status shows connection state, but it does not prove a source has been downloaded; check integrations download list too. You can also run these commands manually or from a script. Use --help for the full options and --dry-run to preview a supported write request without making the change.

Only upload a policy document after the support owner approves the exact file and target. For the following evaluation, replace the target with an approved non-production teammate and set consequential connected actions to Disabled in Actions and Approvals. Fictional inputs and “do not act” prompts do not enforce that boundary. Chat is billed work; approve the budget before running it. Start a fresh named conversation for each test:

npx @eesel/cli files upload ./approved-support-policy.pdf --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli new --name "refund-policy-review" --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli chat "Fictional case: a customer asks for a refund but has no order number. State the policy facts, list the missing information, and say whether to hand off to a person. Do not send a message, modify configuration, approve an action, or promise a refund." --agent "$TARGET_EESEL_AGENT"

Check the uploaded document's processing state before testing; a connection or download-status check alone does not prove the answer used that policy. Review the answer, activity, and any held approvals against the approved document. Test at least three cases in fresh conversations: an eligible refund, an ineligible refund, and missing information or a request for a person. Do not invent eligibility thresholds that the document does not state. Any later delivery or routing check in a real helpdesk needs its own approved test plan.

Choose CLI commands or an MCP connection

To expose the workspace as tools inside Claude Code, run npx @eesel/cli mcp token --agent "$TARGET_EESEL_AGENT", then use the generated setup command to configure the client. The eesel MCP guide explains the URL, headers, token lifetime, and role permissions.

For CI or a server, the eesel CLI uses EESEL_API_URL and EESEL_API_TOKEN for access and EESEL_AGENT_ID for agent selection. Those settings configure eesel access; they do not replace Claude Code's own account or permissions.

The result is a shared support teammate that can be operated from a coding session, scripts, or the dashboard. You can inspect instructions, manage automations, review actions waiting for approval, and read activity without creating a separate copy of the agent.

Claude Code access and pricing

Claude Code requires a paid access path; the free Claude.ai plan does not include it. Anthropic currently supports Claude Pro, Max, Team, Enterprise, and Console accounts, and it also supports some third-party API providers. Team and Enterprise access can depend on the organization’s seat configuration.

Prices, regional availability, and usage limits change, so check Anthropic’s current pricing before choosing a plan. For a company rollout, ask the administrator which account type and model policy apply before writing team settings.

Add an eesel CLI workflow to your Claude Code terminal

Start with a shared settings.json, a short CLAUDE.md, and only the permissions your project needs. Test hooks on one safe file before applying them across a repository. That gives Claude Code useful context and keeps approvals understandable.

For a support setup task, use the eesel CLI from Claude Code to inspect the intended teammate, upload an owner-approved policy document, and test eligible, ineligible, and missing-information cases in a fresh conversation. eesel is the support teammate your team can operate in the dashboard; Claude Code is the coding environment that can help run that workflow. Keep the named --agent target in every command so the result is reviewable by the support team.

Try eesel when you want a support teammate your team can test from the terminal and manage from the dashboard.