# Hot Paths

> |

- **Type:** Skill
- **Install:** `agentstack add skill-techymt-claude-code-superpowers-hot-paths`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [TechyMT](https://agentstack.voostack.com/s/techymt)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [TechyMT](https://github.com/TechyMT)
- **Source:** https://github.com/TechyMT/claude-code-superpowers/tree/main/skills/hot-paths

## Install

```sh
agentstack add skill-techymt-claude-code-superpowers-hot-paths
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Hot Paths

## The pattern

Claude Code has three hot paths: **startup** (module loading before first prompt), **per-turn** (context assembly before each API call), and **per-tool-call** (schema validation and permission checking for every tool use). Each has different performance constraints and different techniques.

For startup: use `lazySchema()` to defer Zod parsing, use `feature()` flags to eliminate dead code at build time, parallelize independent I/O with `Promise.all()`, and track timing with `profileCheckpoint()`.

For per-turn: memoize expensive computations (git status, file system state) that don't change mid-conversation. Clear memoized values only when the underlying state actually changes.

For per-tool-call: `lazySchema()` ensures schema objects are built at most once per process lifetime (on first access), not once per call.

## Why this matters

Claude Code starts a new process on every invocation. Users expect the prompt to appear in under a second. With ~512K lines of TypeScript across 1,884 files, naive module loading would be too slow. The techniques below are how the team keeps startup under a second on typical developer machines.

The per-turn hot path is also user-visible: every time the LLM needs to generate a response, Claude Code assembles a system prompt that includes git status, open file list, working directory, and recent file changes. This assembly runs before each API call. If it were slow, every turn would feel sluggish.

## How to apply it

**Startup:**
1. Wrap Zod schemas in `lazySchema(() => z.object({...}))` from `utils/lazySchema.ts`. The schema is built only when first accessed, not when the module loads.
2. Use `feature('FLAG_NAME')` from `bun:bundle` for conditional imports. Bun evaluates these at build time and tree-shakes unused code. An unused feature flag means the code is not included in the bundle.
3. Use `profileCheckpoint('label')` to measure time between initialization steps during development.
4. For independent async initialization (config reads, keychain prefetch, MCP connection), use `Promise.all()`.

**Per-turn:**
5. Use `memoize()` from lodash for functions that are expensive and called multiple times per conversation (git status, workspace file enumeration).
6. Clear memoized values via `cache.clear?.()` when the underlying state changes (e.g., after a file write or git commit).

**Per-tool-call:**
7. `lazySchema()` schemas are effectively memoized at module scope — no additional caching needed.
8. For permission rule matching, pre-compile patterns once and reuse them.

## In the source

```typescript
// Source: src/tools/FileReadTool/FileReadTool.ts (lazySchema for deferred init)
import { lazySchema } from '../../utils/lazySchema.js'

// Schema construction deferred until first tool invocation — not at module load
const inputSchema = lazySchema(() =>
  z.object({
    file_path: z.string(),
    limit: z.number().optional(),
    offset: z.number().optional(),
  })
)

// Source: src/main.tsx (feature flags for dead code elimination)
// Bun evaluates feature() at build time — unused modules not in bundle
const assistantModule = feature('KAIROS')
  ? require('./assistant/index.js') as typeof import('./assistant/index.js')
  : null

const kairosGate = feature('KAIROS')
  ? require('./assistant/gate.js') as typeof import('./assistant/gate.js')
  : null

// Source: src/context.ts (memoize for per-conversation caching)
import { memoize } from 'lodash-es'

export const getGitStatus = memoize(async (): Promise => {
  // This runs once per conversation, not once per turn
  // Five git commands parallelized — not sequential
  const [branch, mainBranch, status, log, userName] = await Promise.all([
    getBranch(),
    getDefaultBranch(),
    execFileNoThrow(gitExe(), ['--no-optional-locks', 'status', '--short']),
    execFileNoThrow(gitExe(), ['--no-optional-locks', 'log', '--oneline', '-n', '5']),
    execFileNoThrow(gitExe(), ['config', 'user.name']),
  ])
  // ...
})

// Cache is cleared when state changes (e.g., after git commit)
getGitStatus.cache.clear?.()

// Source: src/main.tsx (profileCheckpoint for startup profiling)
profileCheckpoint('imports_loaded')
await initializeConfig()
profileCheckpoint('config_loaded')
await Promise.all([
  prefetchKeychain(),
  connectMCPServers(),
])
profileCheckpoint('parallel_init_done')
```

The `--no-optional-locks` flag in git commands is a performance detail: by default git acquires a lock file before reading index state. `--no-optional-locks` skips that when the operation doesn't need the lock, saving ~20ms per command. On five parallel commands, this saves ~100ms.

## Apply it to your code

**Before** — schema built at module load, expensive init not parallelized:
```typescript
// Module load time: slow — Zod builds validators immediately
const inputSchema = z.object({
  file_path: z.string(),
  content: z.string(),
  encoding: z.enum(['utf-8', 'base64']).optional(),
})

// Sequential initialization
async function initWorkspace() {
  const config = await readConfig()      // 50ms
  const gitStatus = await getGitStatus() // 120ms
  const files = await listOpenFiles()    // 30ms
  // Total: ~200ms sequential
  return { config, gitStatus, files }
}
```

**After** — lazy schema, parallel init:
```typescript
// Schema deferred — no cost at module load time
const inputSchema = lazySchema(() =>
  z.object({
    file_path: z.string(),
    content: z.string(),
    encoding: z.enum(['utf-8', 'base64']).optional(),
  })
)

// Parallel initialization — total time = slowest operation (~120ms)
async function initWorkspace() {
  const [config, gitStatus, files] = await Promise.all([
    readConfig(),       // 50ms — runs concurrently
    getGitStatus(),     // 120ms — runs concurrently (bottleneck)
    listOpenFiles(),    // 30ms — runs concurrently
  ])
  return { config, gitStatus, files }
}
```

## Signals that you need this pattern

- A new Tool's `inputSchema` is a bare `z.object({...})` at module scope (not wrapped in `lazySchema`)
- Startup time regressed after adding a new module with expensive top-level initialization
- A function called multiple times per conversation (git status, file listing) is not memoized
- Independent async operations in initialization code are awaited sequentially instead of `Promise.all()`-ed
- `feature('FLAG')` is not used for optional large features (assistant mode, voice mode, remote mode)

## Signals that you're over-applying it

- Don't memoize functions whose inputs vary per call — `memoize()` with no cache key returns the same result for all inputs
- Don't use `lazySchema()` for schemas used in tests or utilities — the startup savings are irrelevant there
- Don't parallelize operations that depend on each other's output

## Works with

- `async-concurrency` — Promise.all() for parallel I/O
- `module-organisation` — which modules are lazily loaded
- `types-and-interfaces` — lazySchema() wraps Zod schema definitions

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TechyMT](https://github.com/TechyMT)
- **Source:** [TechyMT/claude-code-superpowers](https://github.com/TechyMT/claude-code-superpowers)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-techymt-claude-code-superpowers-hot-paths
- Seller: https://agentstack.voostack.com/s/techymt
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.