# Claude Code Setup Reference for Apoklisis

This document catalogs all tools, plugins, and MCP servers available to Claude Code when developing Apoklisis, along with guidelines for their effective use.

**Last Updated**: 2026-01-27
**Project**: Apoklisis
**Working Directory**: `c:\Dev\Projects\Apoklisis`
**Platform**: Windows (win32)
**IDE**: VSCode with Claude Code extension

---

## Core Built-In Tools

### File Operations

#### Read
- **Purpose**: Read file contents from the filesystem
- **Capabilities**:
  - Reads up to 2000 lines by default
  - Supports offset/limit for large files
  - Can read images (PNG, JPG), PDFs, and Jupyter notebooks
  - Returns content with line numbers
- **When to use**: Always read files before editing them; use for examining code, configs, or documentation

#### Edit
- **Purpose**: Perform exact string replacements in files
- **Capabilities**:
  - Replaces `old_string` with `new_string`
  - Supports `replace_all` for renaming variables
  - Preserves indentation
- **When to use**: Prefer editing over writing new files; ideal for targeted changes
- **Requirements**: Must read file first before editing

#### Write
- **Purpose**: Create new files or overwrite existing ones
- **Capabilities**: Writes complete file content
- **When to use**: Only for creating genuinely new files; avoid for existing files (use Edit instead)
- **Requirements**: Must read file first if it exists

#### NotebookEdit
- **Purpose**: Edit Jupyter notebook (.ipynb) cells
- **Capabilities**:
  - Replace, insert, or delete cells
  - Supports code and markdown cells
- **When to use**: Working with Jupyter notebooks in the project

### Search & Discovery

#### Glob
- **Purpose**: Fast file pattern matching
- **Capabilities**:
  - Supports glob patterns like `**/*.js`, `src/**/*.ts`
  - Returns files sorted by modification time
- **When to use**: Finding files by name patterns; use for specific needle queries
- **Example**: `**/*.py` to find all Python files

#### Grep
- **Purpose**: Powerful content search (built on ripgrep)
- **Capabilities**:
  - Full regex support
  - Filter by glob or file type
  - Output modes: content, files_with_matches, count
  - Context lines (-A, -B, -C)
  - Multiline matching support
- **When to use**: Searching for code patterns, function definitions, or specific strings
- **Important**: Use Task with Explore agent for open-ended exploratory searches

### Execution & System

#### Bash
- **Purpose**: Execute bash commands
- **Capabilities**:
  - Git operations
  - Package management (npm, pip, etc.)
  - Build commands
  - Testing
  - System operations
- **When to use**: Terminal operations, git, npm, docker, but NOT for file reading/searching (use specialized tools)
- **Best practices**:
  - Use `&&` for sequential dependent commands
  - Quote paths with spaces
  - Avoid `cd`; use absolute paths instead
  - Never skip git hooks unless explicitly requested

#### TaskOutput
- **Purpose**: Retrieve output from running/completed background tasks
- **When to use**: Check status of background shells or agents

#### TaskStop
- **Purpose**: Stop running background tasks
- **When to use**: Terminate long-running processes

### Planning & Task Management

#### TodoWrite
- **Purpose**: Create and manage structured task lists
- **Capabilities**:
  - Track tasks with states: pending, in_progress, completed
  - Organize complex multi-step work
- **When to use**:
  - Complex tasks with 3+ steps
  - Multi-file changes
  - User provides multiple tasks
  - Before starting work on each task
- **Best practice**: Mark todos completed immediately after finishing; maintain exactly ONE in_progress task at a time

#### EnterPlanMode / ExitPlanMode
- **Purpose**: Enter planning mode for implementation design
- **When to use**:
  - New feature implementation
  - Multiple valid approaches exist
  - Architectural decisions needed
  - Multi-file changes
  - Unclear requirements
- **When NOT to use**: Simple one-line fixes, trivial tasks, pure research

#### AskUserQuestion
- **Purpose**: Ask user questions during execution
- **Capabilities**:
  - Multiple choice questions (2-4 options)
  - Multi-select support
  - Collects user preferences and clarifications
- **When to use**: Need clarification on requirements, implementation choices, or ambiguous instructions

### Web & Information

#### WebFetch
- **Purpose**: Fetch and analyze web content
- **Capabilities**:
  - Converts HTML to markdown
  - 15-minute cache
- **Limitations**: WILL FAIL for authenticated/private URLs
- **When to use**: Public documentation, articles, reference materials
- **Note**: For GitHub URLs, prefer `gh` CLI via Bash

#### WebSearch
- **Purpose**: Search the web for current information
- **Capabilities**:
  - Access to up-to-date information beyond knowledge cutoff
  - Domain filtering (allowed/blocked)
- **Requirements**: MUST include "Sources:" section with markdown links in response
- **When to use**: Current events, recent documentation, external references

#### ToolSearch
- **Purpose**: Load deferred MCP tools before use
- **Capabilities**:
  - Keyword search mode (e.g., "slack", "notebook")
  - Direct selection mode (e.g., "select:NotebookEdit")
  - Required keyword mode (e.g., "+linear create issue")
- **When to use**: MANDATORY before calling any deferred/MCP tool
- **Important**: This is a BLOCKING requirement - must load tools before calling them

---

## Specialized Agents (via Task Tool)

The Task tool launches specialized agents for complex work. Each agent type has specific capabilities:

### Bash Agent
- **Specialty**: Command execution
- **Tools**: Bash only
- **When to use**: Git operations, complex command sequences

### general-purpose Agent
- **Specialty**: Complex research and multi-step tasks
- **Tools**: All tools
- **When to use**: Complex questions, keyword searches requiring multiple attempts

### Explore Agent
- **Specialty**: Fast codebase exploration
- **Tools**: Read-only tools (Glob, Grep, Read, etc.)
- **Thoroughness levels**: quick, medium, very thorough
- **When to use**:
  - "Where are errors handled?"
  - "How do API endpoints work?"
  - "What is the codebase structure?"
- **Critical**: Use this instead of manual Glob/Grep for exploratory searches

### Plan Agent
- **Specialty**: Implementation planning and architecture design
- **Tools**: Read-only tools
- **When to use**: Design implementation strategy, identify critical files, consider architectural trade-offs

### feature-dev Agents
- **code-architect**: Design feature architectures
- **code-explorer**: Analyze existing features and patterns
- **code-reviewer**: Review code for bugs and quality issues

---

## Available Skills (via Skill Tool)

Skills are invoked when users reference slash commands (e.g., `/commit`).

### feature-dev:feature-dev
- **Purpose**: Guided feature development with architecture focus
- **When to use**: Building new features from scratch

### frontend-design:frontend-design
- **Purpose**: Create production-grade frontend interfaces
- **When to use**: Building web components, pages, or applications
- **Goal**: Avoid generic AI aesthetics; create polished, distinctive designs

### Figma Integration Skills
- **figma:code-connect-components**: Map Figma designs to code components
- **figma:create-design-system-rules**: Generate custom design system rules
- **figma:implement-design**: Translate Figma designs to production code
- **Requirement**: Figma MCP server connection

---

## MCP Servers (Deferred Tools)

These tools must be loaded via ToolSearch before use.

### GitHub MCP Server
**Prefix**: `mcp__github__*`

**Available Operations**:
- **Repository**: create, fork, search repositories
- **Files**: get contents, create/update files, push files
- **Branches**: create, list commits
- **Issues**: create, list, update, get, add comments, search
- **Pull Requests**: create, list, get, merge, review, get files/status/comments
- **Search**: code, issues, users

**When to use**: GitHub operations beyond what `gh` CLI provides

### Filesystem MCP Server
**Prefix**: `mcp__filesystem__*`

**Available Operations**:
- **Read**: read_file, read_text_file, read_media_file, read_multiple_files
- **Write**: write_file, edit_file
- **Directory**: create, list, tree, list_with_sizes
- **Operations**: move, search files, get file info
- **Management**: list_allowed_directories

**When to use**: Complex filesystem operations; prefer built-in Read/Write/Edit for simple operations

### MS365 MCP Server
**Prefix**: `mcp__ms365__*`

**Available Operations**:
- **Authentication**: login, logout, verify, list/select/remove accounts
- **Teams**: chat operations, channel messages, team management
- **OneDrive**: file operations, Excel operations (worksheets, charts, ranges)
- **Outlook**: mail operations, calendar events, contacts
- **SharePoint**: site operations, lists, items
- **Planner**: tasks and plans
- **OneNote**: notebooks, sections, pages
- **Todo**: task lists and tasks

**When to use**: Integration with Microsoft 365 services

---

## Project-Specific Context: Apoklisis

### Environment
- **Repository**: Git repository on main branch
- **Platform**: Windows (win32)
- **IDE**: VSCode with native Claude Code extension
- **Recent Activity**:
  - Backend fixes: passlib/bcrypt integration (pinned bcrypt to 4.1.2)
  - DateTime timezone issue fixes
  - Clean working tree (as of last snapshot)

### Recent Commits
```
a3efe68 Committing before moving to local disk
a6fc86c Pin bcrypt version to 4.1.2 for passlib compatibility
fa632da Fix backend: add passlib/bcrypt, fix datetime timezone issues
```

### Technology Stack (Inferred)
- **Backend**: Python (passlib, bcrypt for authentication)
- **Key Considerations**:
  - Password hashing with passlib
  - Timezone handling for datetime operations
  - Dependency version compatibility (bcrypt pinned)

### File Reference Format
When referencing code in VSCode, use markdown links:
- Files: `[filename.ts](src/filename.ts)`
- Specific lines: `[filename.ts:42](src/filename.ts#L42)`
- Line ranges: `[filename.ts:42-51](src/filename.ts#L42-L51)`
- Folders: `[src/utils/](src/utils/)`

---

## Development Guidelines

### General Workflow
1. **Read First**: Always read files before editing
2. **Plan Complex Tasks**: Use TodoWrite for multi-step work
3. **Use Specialized Tools**: Prefer dedicated tools over bash commands for file operations
4. **Explore Efficiently**: Use Task with Explore agent for codebase exploration
5. **Parallel Execution**: Make independent tool calls in parallel when possible

### Code Modification Principles
- **Avoid Over-Engineering**: Only make requested changes
- **No Premature Abstraction**: Don't create utilities for one-time operations
- **Security First**: Watch for command injection, XSS, SQL injection, OWASP Top 10
- **Simplicity**: Keep solutions focused and minimal
- **No Unnecessary Additions**: Don't add error handling for impossible scenarios

### Git Best Practices
- **Never** update git config
- **Never** run destructive commands (push --force, reset --hard) without explicit request
- **Never** skip hooks (--no-verify, --no-gpg-sign)
- **Always** create NEW commits (don't amend unless requested)
- **Prefer** staging specific files over `git add -A` or `git add .`
- **Only commit** when explicitly requested
- **Include** co-author tag: `Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>`

### Pull Request Workflow
1. Run `git status`, `git diff`, check branch state
2. Analyze ALL commits from branch divergence (not just latest)
3. Keep PR title under 70 characters
4. Use HEREDOC for PR body with format:
   ```
   ## Summary
   <1-3 bullet points>

   ## Test plan
   [Checklist of testing TODOs]

   🤖 Generated with [Claude Code](https://claude.com/claude-code)
   ```

### Communication Style
- **Concise**: Short, focused responses for CLI display
- **No Emojis**: Unless explicitly requested
- **No Time Estimates**: Never predict how long tasks will take
- **Objective**: Technical accuracy over validation
- **Direct**: Use markdown formatting, output text directly (not via echo/bash)

### When to Ask for Help
- **User Questions**: Use AskUserQuestion for clarifications
- **Planning**: Use EnterPlanMode for complex implementation decisions
- **Feedback**: Direct users to https://github.com/anthropics/claude-code/issues

---

## Quick Reference: Tool Selection Decision Tree

```
Need to find files by name pattern?
  → Use Glob

Need to search for code content?
  → Specific query? → Use Grep
  → Exploratory search? → Use Task (Explore agent)

Need to read a file?
  → Use Read (not cat)

Need to modify existing file?
  → Use Edit (not sed/awk)

Need to create new file?
  → Use Write (not echo/heredoc)

Need to execute command/git/npm?
  → Use Bash

Need to plan complex implementation?
  → Use EnterPlanMode

Need to track multi-step task?
  → Use TodoWrite

Need GitHub/MS365/filesystem MCP operations?
  → First: ToolSearch to load tool
  → Then: Call the loaded MCP tool

Need to ask user a question?
  → Use AskUserQuestion
```

---

## Notes for Future Sessions

- **Context Persistence**: Conversations have unlimited context through automatic summarization
- **Tool Results**: May include `<system-reminder>` tags with useful information
- **Model**: Powered by Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
- **Knowledge Cutoff**: January 2025
- **Current Date**: Always use 2026 in current date calculations

---

## Security Policy

**Defensive Security Only**
- Assist with security analysis, detection rules, vulnerability explanations
- Create defensive tools and security documentation
- **Refuse**: Code for malicious use, credential harvesting, bulk SSH key/cookie/wallet crawling

---

*This reference guide should be consulted at the start of each session to ensure effective use of all available tools and maintain consistency with project conventions.*