# Getting Started with Claude Code

A practical guide to installing, configuring, and getting the most out of Claude Code at Gemma.

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Contents

- [What is Claude Code?](#what-is-claude-code)
- [Installation](#installation)
- [The Foundation: Key Concepts](#the-foundation-key-concepts)
  - [1. CLAUDE.md — Your Project's Instruction Manual](#1-claudemd--your-projects-instruction-manual)
  - [2. Context Window — Claude's Working Memory](#2-context-window--claudes-working-memory)
  - [3. Modes — Control How Claude Works](#3-modes--control-how-claude-works)
- [Extending Claude](#extending-claude)
  - [Anthropic Official Plugins](#anthropic-official-plugins)
  - [Gemma Agentic Toolkit](#gemma-agentic-toolkit)
  - [Third-party plugins](#third-party-plugins)
  - [MCP Servers — Connecting to External Services](#mcp-servers--connecting-to-external-services)
- [Claude Subscription vs. AWS Bedrock (API Usage)](#claude-subscription-vs-aws-bedrock-api-usage)
  - [Switching to Bedrock](#switching-to-bedrock)
- [Permissions — Why They Matter](#permissions--why-they-matter)
  - [1. Server-managed (automatic, you don't need to do anything)](#1-server-managed-automatic-you-dont-need-to-do-anything)
  - [2. Personal permissions (your choice)](#2-personal-permissions-your-choice)
- [Security — Catching Vulnerabilities Before They're Written](#security--catching-vulnerabilities-before-theyre-written)
- [Tips for Effective Use](#tips-for-effective-use)
- [Resources](#resources)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## What is Claude Code?

Claude Code is a command-line AI assistant that lives in your terminal. You describe what you need in plain English, and it reads your files, writes code, runs commands, and helps you think through problems — all within your project folder.

You don't need to be a developer to use it. If you can type in a terminal, you can use Claude Code.

> **How it works:** [How Claude Code Works](https://code.claude.com/docs/en/how-claude-code-works) — official explanation of what happens under the hood.
>
> **Recommended reading:** [Claude Code for Everything, Finally](https://hannahstulberg.substack.com/p/claude-code-for-everything-finally) — a beginner-friendly walkthrough of what Claude Code can do and how to set it up.
>
> **Video introduction:** [Claude Code Overview](https://www.youtube.com/watch?v=mZzhfPle9QU) — a visual walkthrough of Claude Code in action.

---

## Installation

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

Then start it inside any project folder:

```bash
cd ~/projects/my-project
claude
```

That's it. Claude will read your project and start helping.

> **Other platforms or having trouble?** See the [official installation guide](https://code.claude.com/docs/en/getting-started) for macOS, Linux, and Windows instructions.

---

## The Foundation: Key Concepts

Three things are worth understanding before you start.

### 1. CLAUDE.md — Your Project's Instruction Manual

Every project can have a `CLAUDE.md` file at its root. Claude reads this file automatically at the start of every session. It's where you put rules, conventions, and context that Claude should always know.

Same idea as onboarding docs, but for Claude instead of a new hire.

```markdown
# CLAUDE.md

## Project context
This is a dbt project for our Snowflake warehouse.

## Rules
- Always use `uv` to run Python, never `python` directly
- Never commit to `main` — create a feature branch first
- SQL style: lowercase keywords, trailing commas
```

You can also have:
- **`~/.claude/CLAUDE.md`** — personal instructions that apply to all your projects (e.g., "I prefer concise answers")
- **`.claude/CLAUDE.md`** in a project — project-specific instructions checked into git

<details>
<summary>Tips for writing good CLAUDE.md files</summary>

- Keep it short and direct — Claude reads this every session, so don't waste its attention
- Focus on **rules** (what to do and not do) and **context** (what this project is about)
- Include commands Claude will need (how to run tests, how to build, etc.)
- Update it as your project evolves — stale instructions cause stale output
- Don't repeat things Claude can figure out from the code itself

</details>

### 2. Context Window — Claude's Working Memory

Claude has a limited amount of "working memory" called the context window. Every message you send, every file Claude reads, and every command output takes up space in this window.

When the context fills up, Claude compacts it automatically: clearing older tool outputs first, then summarizing the conversation. Long sessions with lots of file reads can lead to Claude "forgetting" earlier instructions or decisions.

In practice:
- Start new sessions for new tasks instead of reusing long conversations
- Be specific about which files to look at — don't ask Claude to "read everything"
- If Claude starts losing track, it's probably time for a fresh session

### 3. Modes — Control How Claude Works

Claude Code has three modes. Press **`Shift+Tab`** to cycle between them:

| Mode | What it does | When to use it |
|------|-------------|----------------|
| **Normal** | Reads files and writes code, asks permission before each action | Default — good for most work |
| **Plan** | Uses read-only tools only, **never modifies files** | When you want to explore ideas, ask questions, or plan an approach before committing to changes |
| **Auto** | Edits files without asking, still asks before running shell commands | When you trust the direction and want to move faster |

Plan mode is worth getting comfortable with early on. Use it to:
- Ask "how would you approach this?" before making changes
- Explore a codebase you're unfamiliar with
- Discuss architecture or trade-offs without risk of unintended edits
- Review what Claude *would* do before letting it do it

Switch to Normal or Auto mode when you're ready to execute.

<details>
<summary>Other useful shortcuts and commands</summary>

| Shortcut / Command | What it does |
|---|---|
| `Shift+Tab` | Cycle between Normal, Plan, and Auto modes |
| `Escape` | Cancel the current action or clear your input |
| `/help` | Show available commands |
| `/permissions` | Manage which tools Claude can use without asking |
| `/compact` | Compress the conversation to free up context |
| `/clear` | Start a fresh conversation (same session) |
| `/cost` | Show how much the current session has used |

</details>

---

## Extending Claude

Plugins extend Claude with skills (specialized instructions and workflows), agents, hooks, and MCP servers. Browse what's available with `/plugin` → Discover, or install the ones below. See the [official plugins documentation](https://code.claude.com/docs/en/discover-plugins) for browsing, installing, and managing plugins.

> The recommendations below are a starting point, not a rulebook. Things change fast in this space. Explore on your own, try things out, and if you discover a workflow that works well for you, share it with the team!

### Anthropic Official Plugins

Install with `/plugin install <name>@claude-plugin-directory`:

| Plugin | What it does |
|--------|-------------|
| **explanatory-output-style** | Adds educational insights — great for learning unfamiliar codebases |
| **feature-dev** | Guided feature development with codebase exploration and architecture agents |
| **code-simplifier** | Review and simplify recently changed code for clarity and maintainability |
| **claude-code-setup** | Analyze a codebase and recommend Claude Code automations (hooks, skills, MCP servers) |
| **skill-creator** | Create and benchmark custom skills with eval-driven quality checks |

There are many more official plugins available — for frontend engineering, markdown file management, and other use cases. Browse the full list with `/plugin` → Discover → filter by Anthropic.

### [Gemma Agentic Toolkit](https://github.com/Gemma-Analytics/gemma-agentic-toolkit)

Our internal plugin marketplace with skills for data engineering, analytics, and infrastructure.

```
/plugin marketplace add Gemma-Analytics/gemma-agentic-toolkit
```

**Recommended plugin sets by role:**

| Role | Plugins |
|------|---------|
| **Data engineering** | gemma-snowflake, gemma-dlt, gemma-airflow |
| **Analytics engineering** | gemma-snowflake, gemma-metabase |

<details>
<summary>All available Gemma plugins</summary>

| Plugin | What it does |
|--------|-------------|
| **gemma-1password** | Store and retrieve secrets with 1Password CLI |
| **gemma-airflow** | Create and manage Airflow DAGs for dlt connectors |
| **gemma-commercial** | Commercial, sales & project management: contracts, proposals, and project workflows |
| **gemma-dlt** | Build, test, debug, and distribute dlt data connectors |
| **gemma-ewah-migration** | Migrate EWAH pipelines to dlt connectors |
| **gemma-infra** | OpenTofu + Ansible infrastructure scaffolding |
| **gemma-kimball** | Kimball dimensional modelling with multi-agent orchestration |
| **gemma-metabase** | Metabase dashboard management and visual QA |
| **gemma-snowflake** | Snowflake key management and access control |
| **gemma-tech-research** | Multi-agent web research and HTML reports |

Install individually: `/plugin install gemma-dlt@gemma-toolkit`

</details>

### Third-party plugins

**superpowers** — Structured workflows for planning, brainstorming, TDD, debugging, and code review. By [Jesse Vincent](https://github.com/obra/superpowers).
```
/plugin install superpowers@claude-plugin-directory
```

**dbt Labs — dbt Agent Skills**
```
/plugin marketplace add dbt-labs/dbt-agent-skills
/plugin install dbt@dbt-agent-marketplace
```
Skills for dbt model development, testing, semantic layer, job troubleshooting, and migrations. [GitHub](https://github.com/dbt-labs/dbt-agent-skills)

### MCP Servers — Connecting to External Services

MCP (Model Context Protocol) servers let Claude talk to external tools and services: Google Sheets, Todoist, Linear, Slack, GitHub, calendars, and others. They open a live connection to the service and let Claude read and write data through it.

Skills, by contrast, are bundles of instructions and scripts that run locally. They don't consume extra tokens communicating with external APIs, which makes them faster and cheaper. Prefer skills when they cover your use case. Reach for MCP servers when you actually need Claude to interact with an external service in real time, like pulling data from a spreadsheet or creating tasks in a project tracker.

You can ask Claude to search for and install MCP servers for you — just describe the service you want to connect to. For manual setup and the full list of available servers, see the [official MCP documentation](https://code.claude.com/docs/en/mcp).

---

## Claude Subscription vs. AWS Bedrock (API Usage)

Claude Code at Gemma can connect through two different backends:

| | Claude Team subscription (default) | AWS Bedrock |
|---|---|---|
| **When to use** | General coding, refactoring, documentation, planning | Working with databases or client data |
| **Cost** | Flat rate (included in Claude Team subscription) | Per-token (more expensive) |
| **Data path** | Through Anthropic's servers | Stays within Gemma's AWS account |
| **Database access** | Blocked (automatic guardrails) | Allowed |
| **Default model** | Opus 4.6 (configurable) | Sonnet 4.6 (configurable) |

Use the default subscription for everyday work. Switch to Bedrock when you need to touch databases or client data, and switch back when you're done.

### Switching to Bedrock

See the [Bedrock setup guide](https://github.com/Gemma-Analytics/gemma-infrastructure/blob/main/anthropic/SETUP-GUIDE.md) for AWS credentials, the toggle script, and usage instructions (`bedrock-on` / `bedrock-off` / `claude-db`).

---

## Permissions — Why They Matter

Permissions control what Claude is allowed to do in your terminal. Every time Claude wants to run a command, read a file, or write something, it checks the permission rules first.

At Gemma, permissions are managed at **two levels**:

### 1. Server-managed (automatic, you don't need to do anything)

Your Claude for Teams admin account includes **deny rules** that automatically block dangerous operations when you're on the Anthropic API connection. These are deployed centrally — they apply to everyone on the team without any local setup.

What's blocked automatically:
- **Database CLIs** — `psql`, `mysql`, `snowsql`, `duckdb`, `mongosh`, `bq`, `dbt show`, and others
- **Python database libraries** — SQLAlchemy, psycopg, Snowflake connector, PyMongo, etc.
- **MCP database servers** — PostgreSQL, MySQL, Snowflake, BigQuery, and other MCP tools
- **Secrets and credentials** — `.env` files, private keys (`.pem`, `.p8`, `.key`), SSH keys, AWS credentials, service account JSON files, vault tokens

These blocks only apply on the Anthropic API path. When you switch to Bedrock (`bedrock-on`), they're lifted because your data stays within Gemma's AWS account.

A **data-protection system prompt** is also injected into every session automatically, catching things that tool rules can't block — like writing SQL into a file or analyzing a CSV that contains client data.

<details>
<summary>Full list of blocked patterns</summary>

See [`gemma-infrastructure/anthropic/README.md`](https://github.com/Gemma-Analytics/gemma-infrastructure/blob/main/anthropic/README.md) for the complete reference of every blocked command, file pattern, and MCP server.

</details>

### 2. Personal permissions (your choice)

On top of the server-managed rules, you can configure your own permission preferences. This controls how often Claude asks "can I do this?" during a session.

```
/permissions
```

Good candidates to pre-allow: `ls`, `cat`, `git status`, `git diff`, file reads in your project directory. This reduces friction without compromising safety — the server-managed deny rules still apply regardless of your personal settings.

---

## Security — Catching Vulnerabilities Before They're Written

The permissions and data-protection rules above prevent Claude from *accessing* things it shouldn't. But Claude can also introduce security vulnerabilities in the code it *writes* — just like any developer can. The **security-guidance** plugin catches these at write time.

```
/plugin install security-guidance@claude-plugins-official
```

It adds a `PreToolUse` hook that inspects every file edit before it's applied. When it detects a risky pattern, it **blocks the edit** and shows Claude a detailed warning with the safe alternative. Claude then rewrites the code to fix the issue before it ever hits disk. The warning fires once per file per session to avoid noise.

**Patterns it catches:**

| Category | What it detects | Risk |
|----------|----------------|------|
| **GitHub Actions** | Untrusted input (`github.event.issue.title`, PR bodies, commit messages) used directly in `run:` blocks | Command injection |
| **JavaScript** | `eval()`, `new Function()`, `document.write()` | Code injection |
| **React** | `dangerouslySetInnerHTML`, `.innerHTML =` | XSS |
| **Python** | `os.system()` with dynamic args | Command injection |
| **Python** | `pickle` with untrusted data | Arbitrary code execution |

These are patterns that are easy to miss in code review, especially when Claude generates large diffs quickly. The hook acts as an automated security reviewer that never gets tired.

---

## Tips for Effective Use

1. **Start with Plan mode** when you're not sure what to do. Let Claude think it through, then switch to Normal mode to execute.

2. **Be specific.** "Fix the bug in the login form" works better than "fix everything." Include file names if you know them.

3. **Use fresh sessions.** When switching to a different task, start a new session (`/clear` or open a new terminal). Long conversations lose quality.

4. **Let Claude read first.** Instead of pasting code into your message, let Claude read the actual files. It gets more context that way.

5. **Check the output.** Claude gets things wrong sometimes. Review diffs before approving, especially for unfamiliar code.

6. **Ask Claude to interview you.** When requirements are unclear, tell Claude to ask you questions until it has enough context. "Interview me about what this should do before you start" works surprisingly well.

7. **Use CLAUDE.md.** A few minutes writing project instructions saves you from repeating yourself every session.

---

## Resources

| Resource | Link | Notes |
|----------|------|-------|
| Official documentation | [code.claude.com](https://code.claude.com) | The best source for up-to-date information and in-depth explanations of how Claude Code works |
| Beginner's guide | [Claude Code for Everything, Finally](https://hannahstulberg.substack.com/p/claude-code-for-everything-finally) | Friendly walkthrough aimed at non-developers — great first read |
| Video walkthrough | [Claude Code Overview (YouTube)](https://www.youtube.com/watch?v=mZzhfPle9QU) | Visual introduction if you prefer watching over reading |
| Bedrock setup guide | [`SETUP-GUIDE.md`](https://github.com/Gemma-Analytics/gemma-infrastructure/blob/main/anthropic/SETUP-GUIDE.md) | Step-by-step AWS credentials and toggle setup for database work |
| Gemma plugin toolkit | [`gemma-agentic-toolkit`](https://github.com/Gemma-Analytics/gemma-agentic-toolkit) | Full list of Gemma plugins, installation instructions, and development guide |
| Data protection policy | [`anthropic/README.md`](https://github.com/Gemma-Analytics/gemma-infrastructure/blob/main/anthropic/README.md) | Full reference of blocked commands, file patterns, and the rationale behind our two-provider setup |
| Plugin directory | `/plugin` → Discover | Browse and install community and official plugins directly inside Claude Code |