AI Coding Assistants in the Terminal: A Complete Setup Guide

    This guide walks through a practical setup for running an AI coding assistant in the terminal. It covers how to choose an installation method and prepare the runtime, how to scope configuration across enterprise, project, and user levels, how to keep project conventions in a memory file, how to connect external data and tools through the Model Context Protocol (MCP), how to package repeatable workflows as custom skills, and how to point the assistant at third-party or self-hosted models. It also includes security and permission guidance, a verification checklist for new model endpoints, and a troubleshooting table for the most common issues.

    1. Introduction: Why Run an AI Coding Assistant in the Terminal

    Using an AI coding assistant in the terminal has become an everyday habit for many developers. Unlike completion features inside a graphical editor, agent-style terminal tools can carry a task through several steps in a single session: understand the request, read multiple files, modify code, run tests, inspect logs, and adjust the approach based on what they find. This “perceive — plan — execute — review” loop removes the cost of constantly switching between windows and copy-pasting context.

    From an engineering perspective, terminal tools have three clear advantages:

    • They work where the real work happens: the assistant faces the actual project files, shell environment, and version control system, so what it reads is the true state of the codebase.
    • They are easy to automate and integrate: a command-line entry point can be embedded in scripts, CI pipelines, or containers, so the same capability works locally and in a pipeline.
    • Their extension boundaries are clear: through a standardized protocol for connecting external capabilities, reusable custom skills, and swappable underlying models, teams can expand the setup incrementally.

    The flip side is that more capability raises the bar for configuration, permissions, and security. This article focuses on four areas:

    1. Choosing an installation method and preparing the environment;
    2. Connecting external data and tools through the context protocol;
    3. Capturing team experience as custom skills;
    4. Adding third-party models to meet cost, compliance, and capability needs.

    The goal is a setup that is stable, controllable, and reusable, without a long ramp-up.

    2. Step 1: Installation Method and Runtime Preparation

    2.1 Start with the runtime requirements

    Some terminal assistants are built on a scripting runtime. In that case, version 18 or later of the LTS (long-term support) line is usually the minimum. There are three main reasons:

    • Newer runtime releases support modern asynchronous and modular syntax more completely;
    • Package installation is more stable;
    • Security patches are maintained for longer.

    Check what you have installed:

    1. # Check the runtime version; the major version should be 18 or higher
    2. node --version
    3. # Check the version of the runtime's package manager
    4. npm --version
    5. # Detect whether multiple runtime versions exist on PATH
    6. command -v node

    If several runtime versions are installed, pin the project to one of them with a version manager. This avoids the classic “works in terminal A, fails in terminal B” problem.

    2.2 Two installation methods: why the native installer is usually better

    Global installation through a scripting runtime’s package manager was historically the most common way to install a terminal assistant:

    1. # Method 1 (legacy, not recommended): global install via the runtime's package manager
    2. npm install -g <cli-package-name>

    This approach has a hidden prerequisite: the tool shares the host’s runtime and dependency tree. If the local runtime is too old, or the package conflicts with other globally installed packages, installation failures and version confusion are likely.

    Starting with the 2.x major releases, many projects have marked this method as deprecated. For day-to-day use, there is usually no reason to keep it.

    The native installer is the safer choice in most cases:

    1. # Method 2 (recommended): native install script
    2. # Usually ships or bundles the runtime it needs instead of depending on the host version
    3. curl -fsSL <official-install-script-url> | bash
    Aspect Global install via package manager (legacy) Native install script (recommended)
    Dependency on the host runtime Strong, specific version required Weak, typically self-contained
    Version and dependency conflicts More likely Isolated, limited impact
    Control over the install result Depends on global package state Installs to a chosen directory, easier to manage
    Best fit Sharing a runtime with other scripted tools Everyday use by individuals and teams
    Upgrades Re-run the global install command Most builds ship a built-in update command

    2.3 Install, verify, and upgrade

    Placeholders and example fields below are generic. The actual package names, script URLs, and configuration fields should be taken from the official documentation of the tool you use.

    1. # Recommended: run the native install script
    2. curl -fsSL <official-install-script-url> | bash
    3. # Verify: confirm the command is on PATH and reports a version
    4. claude --version
    5. # Upgrade: most versions provide a built-in update command
    6. claude update
    7. # Uninstall: prefer the built-in command, then remove user-level configuration
    8. claude uninstall

    A few practical notes:

    • Prefer the built-in update mechanism: new releases usually bring capability improvements and bug fixes.
    • Use an internal mirror in enterprise environments: download the package, verify it against the officially published checksum, then distribute it through your internal artifact repository.
    • Review before running in audited or isolated environments: download the script and inspect it first; this is safer than piping it straight into a shell.
    • Back up configuration before cleanup: user-level configuration normally lives in a hidden directory under the home directory (for example ~/.claude/), so back up any custom configuration before uninstalling.

    3. First Run: Login, Scopes, and Project Memory

    3.1 Three entry points

    After installation, a terminal assistant typically offers:

    • Interactive session: launched inside the project directory, suited to exploring code, making incremental changes, and debugging;
    • One-shot task mode: a single non-interactive call via -p "<task description>" that writes results to standard output, suited to scripts and pipelines;
    • Configuration update mode: adds, removes, or adjusts configuration items without hand-editing files and introducing syntax errors.
    1. # Start an interactive session (the first launch usually guides you through login or credential setup)
    2. claude
    3. # One-shot mode: ask for the two-level directory structure of src, using read-only commands
    4. claude -p "Output the two-level directory structure of src in the current directory, using read-only commands only"

    Note that the working directory you start in determines which files the assistant can reach by default. Start from the project root rather than a sensitive location such as the home directory.

    3.2 Configuration scopes and precedence

    Mature tools use layered configuration. Common scopes, with higher precedence overriding lower ones:

    Scope Typical location Use case
    Enterprise (managed policy) System-level directory, maintained centrally Disabling high-risk capabilities, enforcing a default model, enabling audit logging
    Project local Inside the project, excluded from version control Personal, temporary preferences for one project
    Project shared Inside the project, committed with the repository Team-wide allow rules, hooks, external capability declarations
    User Configuration directory under the home directory Global personal preferences, credentials, global skills

    This structure matters for three reasons:

    • Team conventions travel with the code: after cloning, everyone gets the same behavior without verbal agreement.
    • Personal preferences stay out of team configuration: write temporary adjustments to the project-local scope.
    • Organizational requirements can be enforced: enterprise policy has the highest precedence and holds the security baseline without relying on individual discipline.

    3.3 Project memory: teaching the assistant your “house rules”

    Placing a memory file in the project root (usually CLAUDE.md) continuously communicates project conventions to the assistant, for example:

    • Tech stack and dependency management rules;
    • Directory structure and responsibilities;
    • Code style and commit message conventions;
    • Testing requirements and verification commands;
    • Explicitly forbidden actions.

    Example:

    1. # Project notes (sample CLAUDE.md)
    2. ## Tech stack
    3. - Runtime: Node.js 22 LTS
    4. - Test framework: the unit testing framework already used by this project
    5. ## Development conventions
    6. - Every new dependency must be justified and pinned to an explicit version
    7. - Commit messages follow "type(scope): description"
    8. - Never push directly to main; all changes land through a pull request
    9. ## Common commands
    10. - Install dependencies: npm ci
    11. - Run tests: npm test
    12. - Lint: npm run lint
    13. ## Notes
    14. - Secrets in configuration files must never be committed
    15. - Changes to core modules must add or update unit tests

    Three practices make memory files work:

    1. Keep them short: include only what the assistant must follow consistently; excessive length dilutes the important parts.
    2. Keep them close to the code: memory files in subdirectories take effect when the assistant works in those directories, which suits module-level notes.
    3. Keep them current: update the file when the tech stack or conventions change, or stale rules will mislead the assistant.

    4. Connecting External Capabilities: the Context Protocol (MCP)

    4.1 The problem it solves

    With local files and a shell alone, there is a limit to what an assistant can do. It has no visibility into production alerts and cannot read the interface contract stored in an internal knowledge base. The Model Context Protocol (MCP) provides a standardized plugin interface so the assistant can call external data sources and tools in a consistent way.

    In the protocol model:

    • Host: the terminal assistant itself; it starts sessions and manages permissions.
    • Client: the component inside the host that maintains a one-to-one connection with each external capability server.
    • Server: the side that exposes capabilities, and it can provide three kinds:
      • Tools: operations the model can call, such as query, create, or update;
      • Resources: readable data such as files, records, and documents;
      • Prompt templates: predefined interaction templates.

    Diagram:

    1. ┌──────────────── Terminal assistant (Host) ────────────────┐
    2. │ Session management / permission approval / context assembly │
    3. │ │ │ │ │
    4. │ Client A Client B Client C │
    5. └──────┼────────────┼─────────────┼──────────────────────────┘
    6. │ stdio │ remote HTTP │ stdio
    7. ▼ ▼ ▼
    8. Local server A Hosted service B Local server C
    9. (DB / code host) (knowledge base / monitoring) (build / release system)

    Once external capabilities are connected, the assistant goes from “a tool that understands code” to “a tool that connects the whole delivery pipeline.” For example:

    • Before committing, look up the requirement and acceptance criteria in the issue tracker;
    • While debugging production, pull metrics and error stacks from monitoring and logging services;
    • While writing an interface, search the internal knowledge base for the API specification and examples.

    4.2 Three connection scopes

    Scope Typical command Where configuration is stored Use case
    Local claude mcp add <name> -- <launch command> User-level configuration Personal local tools
    Project claude mcp add --scope project <name> -- <launch command> Declaration file committed with the repository Team sharing, reproducible
    User claude mcp add --scope user <name> ... User-level configuration Personal reuse across projects

    The assistant can also suggest a suitable set of external connections for the current project based on a description. Treat this as a suggestion only; the decision to adopt it is yours.

    4.3 Configuration and management examples

    1. # Add a local stdio server and pass in an access credential
    2. claude mcp add issue-tracker \
    3. --env ISSUE_TRACKER_TOKEN=<access-token> \
    4. -- npx -y <issue-tracker-mcp-package>
    5. # Connect a hosted remote service in a way the whole team shares
    6. claude mcp add --scope project --transport http knowledge-base https://<internal-knowledge-base-url>/mcp
    7. # Check connection status and the number of available tools
    8. claude mcp list
    9. # Show details for one server (tools, resources, prompt templates)
    10. claude mcp get issue-tracker
    11. # Remove a server (add --scope project to also update the repository declaration)
    12. claude mcp remove issue-tracker

    There are three main transports:

    • stdio: the host starts the server as a local process and communicates over standard input/output; good for local tools.
    • Local HTTP: the service listens on a port on the local machine.
    • Remote HTTP: connects to a hosted service on an internal network or in the cloud.

    You can also reference an external resource directly in the conversation without declaring a server in advance:

    1. Read the code changes in @pr:#123 and, together with the bug description, summarize the fix.

    For services you connect to often, use a fixed configuration. The assistant then stops asking for confirmation each time, and the team configuration can be reviewed.

    4.4 Security and troubleshooting

    • Least privilege: give each server its own scoped, restricted credentials, and prefer read-only access.
    • Keep credentials out of files: inject them via environment variables or a secret manager instead of committing them.
    • Verify the source of remote services: use trusted endpoints and enable transport encryption.
    • Watch for indirect prompt injection: external data may contain misleading instructions, so high-risk operations still need human confirmation.
    • Disable stale servers: remove services that are no longer maintained or whose origin is unclear.

    Typical troubleshooting paths:

    • Server not listed: check the declaration file location, whether environment variables take effect, and whether the launch command runs on its own.
    • Unexpected tool count: confirm the server completed its handshake and is not exposing only part of its capabilities.
    • Permission errors: operations touching system directories may require enabling the appropriate sandbox or directory access configuration.

    5. Custom Skills: Turning Domain Knowledge into Reusable Capability

    5.1 From repeating yourself to writing it down once

    A familiar situation: every time you ask the assistant to do the same kind of task, you repeat the same instructions:

    • which files to inspect;
    • which commands to run;
    • what format the output should take;
    • which actions are off-limits.

    Custom skills exist to solve that repetition. They capture the steps, constraints, and reference material needed for a class of tasks as a reusable knowledge package that loads when it is needed.

    5.2 How it works: progressive disclosure

    A skill is typically a directory containing an instruction file. The header metadata of that file carries fields such as the name and description, while the body describes the concrete steps; scripts and reference material can be attached.

    1. project root/
    2. ├── CLAUDE.md
    3. └── .claude/
    4. └── skills/
    5. └── release-check/
    6. ├── SKILL.md # instruction file: metadata + steps
    7. ├── scripts/
    8. │ └── verify.sh # deterministic logic belongs in scripts
    9. └── references/
    10. └── checklist.md # reference detail, loaded on demand

    Loading follows a progressive disclosure principle:

    1. At startup: only each skill’s name and description are injected into the context, which is cheap.
    2. When a task matches: the assistant uses the description to decide relevance and reads the body only if it matches.
    3. When detail is needed: attached scripts and reference files are read on demand.

    Because of this, a skill library can grow large while each session only pays the context cost relevant to the current task.

    5.3 Example: a pre-release check skill

    1. ---
    2. name: release-check
    3. description: Pre-release check. Use when the user prepares a release, runs pre-release checks, or mentions "release", "ship", or "go live". Verifies code quality, test results, changelog, and version consistency.
    4. ---
    5. # Pre-release check
    6. ## When to use
    7. - Before merging into main
    8. - Before running the release process
    9. ## Steps
    10. 1. Run `scripts/verify.sh`; if it exits non-zero, stop immediately and report the failures
    11. 2. Collect unmerged changes and compare them against the changelog item by item
    12. 3. Confirm the version bump matches the change type (minor for features, patch for fixes)
    13. 4. Report the conclusion: pass / fail, plus any remaining to-dos
    14. ## Constraints
    15. - Never merge, tag, or trigger a deployment automatically
    16. - Any operation that modifies files must be confirmed by the user before committing
    17. - The conclusion must include the commands actually run and key output; no guessing

    5.4 Five tips for writing good skills

    1. Spell out the trigger conditions in the description: include the phrasings users actually say, such as “release”, “ship”, or “go live”, to improve automatic matching.
    2. Keep the body lean and push detail to references: put only core steps in the body and long specifications in the references directory.
    3. Use scripts for deterministic logic: format validation and command assembly should not be improvised by the model.
    4. State constraints and prohibitions: make explicit which operations must not run automatically and which need human confirmation.
    5. Provide input and output examples: show the assistant what the result should look like.

    5.5 Positioning and governance

    Skills are not the right answer for everything. A rough guide:

    Need Recommended vehicle
    Conventions that always apply (tech stack, commit rules) Project memory file
    Repeatable workflows (release checks, API integration testing) Custom skill
    Operations whose invocation is essentially fixed each time Custom slash command (command file)
    Large subtasks that need an independent context Subagent
    Data and actions that require external systems MCP server

    When rolling skills out to a team, keep the skills directory in version control, use consistent naming, and periodically review whether descriptions are still clear and steps still valid, retiring skills that are no longer used.

    6. Third-Party Models: Picking the Right “Brain” per Scenario

    6.1 Why switch models

    A terminal assistant is only a shell; its understanding and decision-making come from the underlying large language model. The default model is not always the best choice:

    • Cost: simple, repetitive tasks can run on a cheaper, faster model.
    • Compliance: some organizations have explicit requirements about data residency or outbound transfer and need an in-region or self-hosted model service.
    • Capability: models differ in long-context comprehension, reliability of tool calls, and code generation.
    • Autonomy: being able to switch models avoids lock-in to a single vendor.

    6.2 Three ways to configure it

    (1) Quick switch inside a session

    1. # Show the current model along with account and organization information
    2. claude status
    3. # Switch model inside an interactive session (you can also type /model)
    4. claude --model <model-alias>

    If the model name is not recognized, type /model in an interactive session and pick from the list. This is convenient for comparing models on the same task.

    (2) Environment variables

    1. # Default model
    2. export ANTHROPIC_MODEL=<model-name>
    3. # Small, fast model used for background tasks such as summaries and commit messages
    4. export ANTHROPIC_SMALL_FAST_MODEL=<lightweight-model-name>

    (3) Central configuration through settings.json

    1. {
    2. "model": "<model-name>",
    3. "env": {
    4. "ANTHROPIC_BASE_URL": "https://<model-gateway-url>",
    5. "ANTHROPIC_AUTH_TOKEN": "<access-token>",
    6. "ANTHROPIC_MODEL": "<model-name>",
    7. "ANTHROPIC_SMALL_FAST_MODEL": "<lightweight-model-name>"
    8. }
    9. }
    • ANTHROPIC_BASE_URL: the endpoint of a model service that exposes a compatible API;
    • ANTHROPIC_AUTH_TOKEN: the access token; inject it from an environment variable or secret manager rather than writing it into a file that gets committed;
    • ANTHROPIC_MODEL / ANTHROPIC_SMALL_FAST_MODEL: the main model and the lightweight model respectively.

    For enterprise users, administrators can also lock the permitted models and endpoints through managed policy so that individual settings cannot bypass organizational compliance requirements.

    6.3 What to evaluate in a third-party model

    When choosing a model service with a compatible API, assess the following:

    1. API compatibility: are message formats, streaming output, and authentication headers the same, and is extra adaptation needed?
    2. Tool call support: the assistant relies on function calling to run commands and read or write files; incomplete support noticeably degrades execution.
    3. Context window: a small window forces truncation during long-file analysis or multi-file refactoring.
    4. Long-context handling: some services compress the middle of very long inputs, which can affect attention to detail.
    5. Default parameters: if defaults such as temperature differ from what the assistant expects, output stability may drop.
    6. Rate limits and timeouts: concurrency and rate limits should match your team size, with sensible timeout and retry policies.
    7. Data and compliance: confirm whether data is retained or used for training, and whether sensitive code is allowed to leave your network.

    After configuring, validate from simple to complex:

    1. Basic conversation: confirm connectivity and authentication.
    2. Single-file change: check that the diff matches expectations.
    3. Multi-file refactoring: see whether the context is sufficient.
    4. Tool calls: confirm file reads and writes and command execution work.
    5. Long-running task: record duration and failure rate.

    On that basis, assign models per task type using cost, speed, and success rate. A lightweight model for routine questions and a more capable model for complex refactoring is a common split.

    6.4 Managed model services and gateways

    If your team already runs a cloud model platform, the practical path is to provision the models you need, create an access token, and substitute the endpoint and token values in the configuration above. For security, keep tokens in a controlled secret manager or configuration center instead of storing them in plaintext in a code repository. Availability, API specifications, and pricing vary by provider and region, so confirm the exact model list, interface contract, and billing terms against the official documentation — for organizations using Baidu AI Cloud, for example, its model service platform documentation is the reference.

    An API gateway in front of the model service can centralize credential management, call quotas, and audit logs, giving the team “configure once, reuse everywhere” behavior.

    7. Troubleshooting Checklist

    Symptom Likely cause Fix
    Command not found after installation Install directory is not on PATH Add it to PATH or reopen the terminal
    Installation fails or reports a version error Runtime is older than 18 Upgrade to an LTS release or use the native installer
    Prompt to log in on startup Credentials missing or expired Re-run login or refresh the environment variables
    Assistant modifies files beyond its remit No explicit prohibitions Define boundaries in the memory file and allow rules; keep human confirmation for high-risk actions
    External capability does not work Server failed to start or wrong scope Check status with claude mcp list and verify the configuration file location
    Answers ignore project conventions Missing memory file or conflicting layers Add project memory and trim redundant content
    Third-party model behaves unexpectedly Incomplete tool call support, insufficient context window, different defaults Compare models, tune parameters, or pick a better-fitting model

    8. Best Practices

    1. Prefer the native installer unless you genuinely need to share the host runtime and its dependencies.
    2. Manage configuration in layers: team conventions in the repository, personal preferences at user scope, organizational requirements in managed policy.
    3. Keep memory files short and useful: retain only what the assistant must follow long term.
    4. Grant external capabilities the minimum access: connect them per project, host credentials centrally, and rotate them regularly.
    5. Capture team experience as skills: turn high-frequency workflows into skills you write once and reuse for a long time.
    6. Choose models per scenario: balance cost, compliance, and capability, and manage them through a shared gateway or policy.
    7. Check the setup periodically: track version updates and configuration changes, and retire stale items.

    9. Conclusion

    Installation is only the starting point. The real value of a terminal AI coding assistant lies in combining the environment, context, knowledge, and model into a system that matches how your team works: the native installer keeps the environment clean, the context protocol connects external data and tools, custom skills capture process knowledge, and a multi-model strategy balances cost against compliance. Once the basics above are in place, start by getting one or two of your most-used skills and a single external capability working end to end, then expand from there. As usage deepens, this system keeps compounding the team’s development efficiency.