Unlocking Claude Code: Deep Dive into Undocumented Configurations and Advanced Hooks

While the official documentation for Claude Code provides a solid foundation, a deep dive into the source code—available as a public npm package—reveals a layer of sophisticated, undocumented capabilities. These features transform Claude Code from a standard AI assistant into a programmable development environment with a middleware layer for tool use and a persistent learning loop.

This guide explores the advanced configurations discovered within the source, focusing on how to extend the tool's behavior through hooks, custom skills, and agent memory.

The Programmable Middleware: Advanced Hooks

The most significant gap in the official documentation is the ability for hooks to return JSON on stdout to modify Claude Code's behavior in real time. While the docs mention that exit code 2 blocks an operation, the source code reveals specific fields that allow for dynamic intervention.

PreToolUse Hooks

PreToolUse hooks can return the following fields to intercept and modify tool execution:

  • updatedInput: Rewrite the tool's input (e.g., automatically adding --dry-run to a git push command).
  • permissionDecision: Force an "allow" or "deny" decision without prompting the user.
  • permissionDecisionReason: Provide a reason for the decision, which is displayed in the UI.
  • additionalContext: Inject text directly into the conversation context.

SessionStart and PostToolUse Hooks

  • SessionStart: Can return watchPaths to trigger automatic file watching, initialUserMessage to prepend content to the first message, and additionalContext for session-wide persistence.
  • PostToolUse: Can return updatedMCPToolOutput to modify what Claude sees from an MCP tool response, and additionalContext to inject context after a tool runs.

Advanced Hook Execution Fields

Beyond the standard type and command fields, the source code parser accepts three critical modifiers:

  • once: true: The hook fires exactly once and then removes itself. Ideal for first-time project setup (e.g., copying .env.example to .env).
  • async: true: Runs the hook in the background without blocking the model's response. Perfect for audit logging.
  • asyncRewake: true: Runs in the background but will "wake" the model and block the operation if the hook exits with code 2. This allows for non-blocking safety scans (like secret detection) that only interrupt the flow when a violation is found.

Extending Capabilities with Custom Skills

Custom skills in .claude/skills/ support frontmatter fields that go beyond the basic documentation, allowing for fine-grained control over model behavior and resource allocation.

Model and Effort Overrides

  • model: Override the default model for a specific skill. You can use haiku for fast, cheap linting and opus for complex architectural reviews.
  • effort: Controls reasoning depth. Options include low, medium, high, or max.

Scoped Hooks and Delegation

  • hooks: You can define hooks that are only active while a specific skill is running. For example, a strict-typescript skill could register a PostToolUse hook that runs tsc on every file edit, which then deregisters once the skill completes.
  • agent: Delegate the skill's execution to a specific custom agent.
  • disable-model-invocation: true: Prevents the model from auto-invoking the skill; it can only be triggered via an explicit /skill-name command.

Persistent Agents and the Learning Loop

Custom agents in .claude/agents/ can be configured for long-term memory and visual distinction.

Agent Memory

The memory field allows agents to maintain state across sessions:

  • user: Global persistence across all projects.
  • project: Persistence specific to the current project.
  • local: Private per-project persistence (typically gitignored).

This enables the creation of agents that learn codebase patterns, remember previous architectural decisions, and track recurring issues over time.

Advanced Agent Configuration

  • color: Sets the UI color (e.g., red, blue, green) to visually distinguish agents.
  • omitClaudeMd: true: Skips loading the CLAUDE.md instruction hierarchy, allowing an agent to review code from first principles without project-specific biases.
  • criticalSystemReminder_EXPERIMENTAL: A short message re-injected at every turn to ensure safety constraints are never lost during conversation compaction.

The "YOLO Classifier" and Auto-Mode

Internally, Claude Code uses a "YOLO Classifier" to determine what can be auto-approved in auto-mode. While pattern matching (e.g., Bash(npm *)) is the primary method, the environment array in settings.json allows you to provide plain English descriptions of your setup.

By adding strings like "This is a local dev machine with no production database access," you provide context that the classifier uses to make safety decisions for ambiguous commands, effectively briefing the AI on the risk profile of your environment.

Self-Improvement: Auto-Memory and Auto-Dream

Two settings enable a compound learning loop that allows Claude Code to evolve without model retraining:

  1. autoMemoryEnabled: Automatically extracts durable memories from sessions and writes them to the project memory store.
  2. autoDreamEnabled: Every 24 hours, a background agent reviews session transcripts to consolidate memories, merge duplicates, and prune stale entries.

Community Perspectives and Caveats

While these features provide immense power, the community has raised important warnings regarding their use. Several users on Hacker News noted that because many of these features are undocumented or buried in the source, they are subject to change without notice.

"Claude package has ten new versions published per week... one should definitely not rely on some undocumented tricks around it: it'll change, it'll break deep ultra-specific configurations."

Furthermore, some users pointed out that as Anthropic updates its documentation, some of these "undocumented" features (like asyncRewake and certain frontmatter fields) are beginning to appear in the official docs, though they may remain difficult to find. Users are also encouraged to look into environment variables for bedrock deployments to further tune model behavior, such as disabling adaptive thinking or telemetry.

Sources