Git & Linux Basics for Agent Developers

8 examples to get you started with git and Linux on an agent project - 5 basic and 3 intermediate.

You will clone a pack layout, branch for a prompt edit, commit and inspect history, navigate the shell around a worker, tail logs, and sketch a tiny local run script.

Prerequisites

Git 2.30+ and a terminal (macOS, Linux, or WSL2)
Python 3.11+ recommended for the local demo agent
No paid APIs required for the sketches below

python -m venv .venv && source .venv/bin/activate
# stdlib only for the examples

Basic Examples

1. Orient Around an Agent Pack Tree

Treat prompts and tools as first-class paths in the repo, not chat paste.

# From the repo root after clone
ls -la
mkdir -p agent_pack/prompts agent_pack/tools deploy/pins
printf '%s\n' 'You are a careful support agent.' > agent_pack/prompts/system_v1.txt
printf '%s\n' '[]' > agent_pack/tools/tools_v1.json
git add agent_pack
git status

Pack paths should be stable and documented for every hire.
Empty tools_v1.json is a list placeholder; real schemas replace it later.
git status is your habit before every commit and after every pull.

Related: Why Agent Teams Still Need Solid Git and Linux Fundamentals

2. Branch Before You Edit a Prompt

Never edit main directly when others share the pack.

git checkout main
git pull --ff-only
git checkout -b prompt/shorten-refund-policy
# edit the file
printf '%s\n' 'You are a careful support agent. Keep refunds under policy v2.' \
  > agent_pack/prompts/system_v1.txt
git diff

Branch names that say what behavior changed help reviewers.
git diff before commit catches accidental whole-file rewrites.
Prefer new version files (system_v2.txt) when your team immutably versions packs.

Related: Git Workflows for Prompt, Tool, and Config Changes

3. Commit With a Behavior-Shaped Message

Commits should explain user-visible or tool-visible impact.

git add agent_pack/prompts/system_v1.txt
git commit -m "prompt: clarify refund policy language for support agent"
git log --oneline -5

Prefixes like prompt:, tools:, eval:, config: make history scannable.
Avoid "update stuff" when the change can break tool selection.
Small commits beat mixed prompt + refactor dumps.

4. Navigate the Shell Where the Worker Runs

Know where you are, what is executable, and what env is set.

pwd
cd "$(git rev-parse --show-toplevel)"
ls -la agent_pack/prompts
echo "USER=$USER HOME=$HOME"
# Never print production secrets; only check that a name exists:
if [ -n "${OPENROUTER_API_KEY:-}" ]; then echo "OPENROUTER_API_KEY is set"; else echo "missing key"; fi

git rev-parse --show-toplevel jumps to repo root from any subdir.
Confirm keys are present, not echoed.
Relative paths in runbooks break when cwd is wrong - pin scripts to repo root.

5. Tail Logs and Find a Python Worker Process

Local and remote debug start the same way: process + recent logs.

# Start a toy worker in the background for demo
python - <<'PY' > /tmp/agent-worker.log 2>&1 &
import time
print("agent-worker ready", flush=True)
while True:
    time.sleep(30)
PY
sleep 0.2
pgrep -af "python" | head
tail -n 20 /tmp/agent-worker.log
# cleanup demo
pkill -f "agent-worker ready" 2>/dev/null || true

Prefer structured logs in real systems; tail -f still works for local files.
pgrep -af shows command lines so you can tell eval jobs from API workers.
On systemd hosts you will use journalctl -u your-agent.service instead of a temp file.

Related: Linux CLI Essentials for Debugging Agent Processes

Intermediate Examples

6. Load a Pack Version From a Pin File

Reproduce "what production would load" on your laptop.

import json
from pathlib import Path
 
ROOT = Path("agent_pack")
PIN = Path("deploy/pins/active.json")
 
 
def write_demo_pin() -> None:
    PIN.parent.mkdir(parents=True, exist_ok=True)
    PIN.write_text(
        json.dumps(
            {
                "prompt_version": "v1",
                "tool_schema_version": "tools_v1",
                "code_sha": "local-dev",
            },
            indent=2,
        ),
        encoding="utf-8",
    )
 
 
def load_system_prompt(pin_path: Path = PIN) -> str:
    pin = json.loads(pin_path.read_text(encoding="utf-8"))
    path = ROOT / "prompts" / f"system_{pin['prompt_version']}.txt"
    return path.read_text(encoding="utf-8").strip()
 
 
write_demo_pin()
print(load_system_prompt()[:60])

Local runs should accept the same pin shape as production.
Do not hardcode "always read system.txt" while prod uses versions.
Log the pin fields when you exercise the agent locally.

7. Stash, Pull, and Rebase a Prompt Branch

Shared packs move while your branch is open.

# On your feature branch after editing
git stash push -m "wip prompt" -- agent_pack
git checkout main
git pull --ff-only
git checkout -
git rebase main
git stash pop
# fix conflicts if any, then:
# git add agent_pack && git rebase --continue

Stash only what you need; avoid stashing secrets files.
Rebase vs merge is a team policy - learn both commands.
Conflict markers in prompts are emergencies, not "fine for later."

Related: Common Git Conflicts in Prompt and Config Files

8. One Script: Run Agent Locally From Clean State

New hires should have a single entrypoint documented in README.

#!/usr/bin/env bash
set -euo pipefail
cd "$(git rev-parse --show-toplevel)"
python -m venv .venv
# shellcheck disable=SC1091
source .venv/bin/activate
pip install -q -r requirements.txt 2>/dev/null || true
export AGENT_PIN_PATH="${AGENT_PIN_PATH:-deploy/pins/active.json}"
python - <<'PY'
from pathlib import Path
import json
pin = json.loads(Path("deploy/pins/active.json").read_text())
print("running with pin", pin)
# import your real agent entrypoint here
PY

set -euo pipefail fails fast on missing vars and bad commands.
Document required env names without pasting secret values into git.
Point onboarding at this script on day one.

Related: Onboarding a New Developer to an Agent Codebase

Why Agent Teams Still Need Solid Git and Linux Fundamentals - why this skill still matters
Git Workflows for Prompt, Tool, and Config Changes - PR recipe for packs
Linux CLI Essentials for Debugging Agent Processes - wider command sheet
Onboarding a New Developer to an Agent Codebase - ramp checklist
Documenting Agent-Specific Conventions for New Team Members - write conventions down
Common Git Conflicts in Prompt and Config Files - conflict playbook
Git, Linux CLI & Team Onboarding Best Practices - section habits
CI/CD & Agent Lifecycle Basics - first eval gate sketches

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

You will clone a pack layout, branch for a prompt edit, commit and inspect history, navigate the shell around a worker, tail logs, and sketch a tiny local run script.

Prerequisites

Git 2.30+ and a terminal (macOS, Linux, or WSL2)
Python 3.11+ recommended for the local demo agent
No paid APIs required for the sketches below

python -m venv .venv && source .venv/bin/activate
# stdlib only for the examples

Basic Examples

1. Orient Around an Agent Pack Tree

Treat prompts and tools as first-class paths in the repo, not chat paste.

# From the repo root after clone
ls -la
mkdir -p agent_pack/prompts agent_pack/tools deploy/pins
printf '%s\n' 'You are a careful support agent.' > agent_pack/prompts/system_v1.txt
printf '%s\n' '[]' > agent_pack/tools/tools_v1.json
git add agent_pack
git status

Pack paths should be stable and documented for every hire.
Empty tools_v1.json is a list placeholder; real schemas replace it later.
git status is your habit before every commit and after every pull.

Related: Why Agent Teams Still Need Solid Git and Linux Fundamentals

2. Branch Before You Edit a Prompt

Never edit main directly when others share the pack.

git checkout main
git pull --ff-only
git checkout -b prompt/shorten-refund-policy
# edit the file
printf '%s\n' 'You are a careful support agent. Keep refunds under policy v2.' \
  > agent_pack/prompts/system_v1.txt
git diff

Branch names that say what behavior changed help reviewers.
git diff before commit catches accidental whole-file rewrites.
Prefer new version files (system_v2.txt) when your team immutably versions packs.

Related: Git Workflows for Prompt, Tool, and Config Changes

3. Commit With a Behavior-Shaped Message

Commits should explain user-visible or tool-visible impact.

git add agent_pack/prompts/system_v1.txt
git commit -m "prompt: clarify refund policy language for support agent"
git log --oneline -5

Prefixes like prompt:, tools:, eval:, config: make history scannable.
Avoid "update stuff" when the change can break tool selection.
Small commits beat mixed prompt + refactor dumps.

4. Navigate the Shell Where the Worker Runs

Know where you are, what is executable, and what env is set.

pwd
cd "$(git rev-parse --show-toplevel)"
ls -la agent_pack/prompts
echo "USER=$USER HOME=$HOME"
# Never print production secrets; only check that a name exists:
if [ -n "${OPENROUTER_API_KEY:-}" ]; then echo "OPENROUTER_API_KEY is set"; else echo "missing key"; fi

git rev-parse --show-toplevel jumps to repo root from any subdir.
Confirm keys are present, not echoed.
Relative paths in runbooks break when cwd is wrong - pin scripts to repo root.

5. Tail Logs and Find a Python Worker Process

Local and remote debug start the same way: process + recent logs.

# Start a toy worker in the background for demo
python - <<'PY' > /tmp/agent-worker.log 2>&1 &
import time
print("agent-worker ready", flush=True)
while True:
    time.sleep(30)
PY
sleep 0.2
pgrep -af "python" | head
tail -n 20 /tmp/agent-worker.log
# cleanup demo
pkill -f "agent-worker ready" 2>/dev/null || true

Prefer structured logs in real systems; tail -f still works for local files.
pgrep -af shows command lines so you can tell eval jobs from API workers.
On systemd hosts you will use journalctl -u your-agent.service instead of a temp file.

Related: Linux CLI Essentials for Debugging Agent Processes

Intermediate Examples

6. Load a Pack Version From a Pin File

Reproduce "what production would load" on your laptop.

import json
from pathlib import Path
 
ROOT = Path("agent_pack")
PIN = Path("deploy/pins/active.json")
 
 
def write_demo_pin() -> None:
    PIN.parent.mkdir(parents=True, exist_ok=True)
    PIN.write_text(
        json.dumps(
            {
                "prompt_version": "v1",
                "tool_schema_version": "tools_v1",
                "code_sha": "local-dev",
            },
            indent=2,
        ),
        encoding="utf-8",
    )
 
 
def load_system_prompt(pin_path: Path = PIN) -> str:
    pin = json.loads(pin_path.read_text(encoding="utf-8"))
    path = ROOT / "prompts" / f"system_{pin['prompt_version']}.txt"
    return path.read_text(encoding="utf-8").strip()
 
 
write_demo_pin()
print(load_system_prompt()[:60])

Local runs should accept the same pin shape as production.
Do not hardcode "always read system.txt" while prod uses versions.
Log the pin fields when you exercise the agent locally.

7. Stash, Pull, and Rebase a Prompt Branch

Shared packs move while your branch is open.

# On your feature branch after editing
git stash push -m "wip prompt" -- agent_pack
git checkout main
git pull --ff-only
git checkout -
git rebase main
git stash pop
# fix conflicts if any, then:
# git add agent_pack && git rebase --continue

Stash only what you need; avoid stashing secrets files.
Rebase vs merge is a team policy - learn both commands.
Conflict markers in prompts are emergencies, not "fine for later."

Related: Common Git Conflicts in Prompt and Config Files

8. One Script: Run Agent Locally From Clean State

New hires should have a single entrypoint documented in README.

#!/usr/bin/env bash
set -euo pipefail
cd "$(git rev-parse --show-toplevel)"
python -m venv .venv
# shellcheck disable=SC1091
source .venv/bin/activate
pip install -q -r requirements.txt 2>/dev/null || true
export AGENT_PIN_PATH="${AGENT_PIN_PATH:-deploy/pins/active.json}"
python - <<'PY'
from pathlib import Path
import json
pin = json.loads(Path("deploy/pins/active.json").read_text())
print("running with pin", pin)
# import your real agent entrypoint here
PY

set -euo pipefail fails fast on missing vars and bad commands.
Document required env names without pasting secret values into git.
Point onboarding at this script on day one.

Related: Onboarding a New Developer to an Agent Codebase

Why Agent Teams Still Need Solid Git and Linux Fundamentals - why this skill still matters
Git Workflows for Prompt, Tool, and Config Changes - PR recipe for packs
Linux CLI Essentials for Debugging Agent Processes - wider command sheet
Onboarding a New Developer to an Agent Codebase - ramp checklist
Documenting Agent-Specific Conventions for New Team Members - write conventions down
Common Git Conflicts in Prompt and Config Files - conflict playbook
Git, Linux CLI & Team Onboarding Best Practices - section habits
CI/CD & Agent Lifecycle Basics - first eval gate sketches

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Git & Linux Basics for Agent Developers

Search Documentation

Git & Linux Basics for Agent Developers