How to Handle State Management with Arc-Kit: A Complete Guide

Arc-Kit handles state management by treating project state as a first-class artifact, using a synchronous context hook to build a complete JSON inventory of your repository once per user prompt and injecting it into the model's context.

State management in the tractorjuice/arc-kit repository eliminates redundant filesystem scans and ensures every slash command operates against a consistent, real-time view of your projects, artifacts, and policies. Instead of letting each command walk the directory tree independently, Arc-Kit centralizes state computation in a single hook that runs before any command executes.

What Is Project State in Arc-Kit?

In Arc-Kit, project state refers to a structured JSON payload that represents the entire architectural inventory of your repository. This includes:

• Project directories under projects/ with their IDs and folder paths
• Artifact metadata including document IDs, types, and status
• External references stored in external/
• Vendor profiles matching vendors/*-profile.md
• Policy documents located in policies/

This state object is built once per user prompt and injected into the model's context, allowing commands to query the repository structure without performing expensive I/O operations.

How the Context Hook Builds State

The core of Arc-Kit's state management lives in arckit-claude/hooks/arckit-context.mjs. This module implements a project-context hook that scans the repository and constructs the JSON inventory.

Hook Registration and Execution

The hook is registered in arckit-claude/hooks/hooks.json to fire on every UserPromptSubmit event. This ensures the inventory is always fresh before any /arckit: command runs.

// Configuration in hooks.json
{
  "hooks": [
    {
      "name": "arckit-context",
      "event": "UserPromptSubmit",
      "script": "arckit-context.mjs"
    }
  ]
}

Synchronous Execution for Immediate Availability

Arc-Kit specifically removed the async flag from this hook to ensure the context arrives in the same turn as the user prompt. According to the CHANGELOG.md, early versions used asynchronous execution, which caused the context to arrive one turn late and broke commands that relied on the inventory.

The hook writes its output to additionalContext, which the model receives as part of the system message.

Size Management and Limits

Because Claude limits hook output to approximately 50KB, the context generator in arckit-context.mjs was optimized to stay under this ceiling. The docs/book/ARCKIT-BOOK.md documents this "Hook output size" guidance, ensuring that large repositories don't exceed context limits while still maintaining comprehensive state coverage.

Accessing State in Commands

Commands within Arc-Kit reference the injected projectState instead of performing their own filesystem scans. This approach decouples command logic from I/O operations and ensures consistency across the toolset.

Here is an illustrative example showing how a custom command might read the injected state to list Terraform state files:

/** Example: a command that lists all Terraform state files */
function listTerraformState(projectState) {
  const tfStates = [];

  // `projectState.projects` is the array built by arckit-context.mjs
  for (const proj of projectState.projects) {
    for (const file of proj.files) {
      if (file.path.endsWith('.tfstate')) {
        tfStates.push({ project: proj.id, path: file.path });
      }
    }
  }

  // Return a concise summary; the model will render it to the user
  return tfStates.length
    ? tfStates.map(s => `- ${s.project}: ${s.path}`).join('\n')
    : 'No Terraform state files found in the current repository.';
}

The projectState object is already populated when the command executes because the hook ran synchronously during the UserPromptSubmit event.

State Management for Infrastructure as Code

Arc-Kit extends its state management philosophy to Infrastructure-as-Code (IaC) workflows. The DevOps guide at docs/guides/devops.md explicitly lists state management as a core sub-topic of Infrastructure-as-Code, ensuring that Terraform, Pulumi, or CloudFormation state files are tracked with the same discipline as architectural artifacts.

Commands like /arckit.devops reference the injected projectState to determine which IaC modules exist, what state files are present, and which drift-detection rules to apply. This alignment ensures that infrastructure state receives the same governance as project artifacts, policies, and external references.

Summary

• Centralized state construction: The arckit-context.mjs hook builds a canonical JSON inventory of your repository once per prompt, eliminating duplicated filesystem scans.
• Synchronous injection: By removing the async flag, state arrives in the same turn as the user prompt, ensuring commands always work with fresh data.
• Size-optimized output: The hook stays under Claude's ~50KB limit through careful optimization, balancing comprehensiveness with context window constraints.
• Command decoupling: Commands consume projectState instead of performing I/O, making them faster and more consistent.
• IaC alignment: Infrastructure state management follows the same disciplined approach as architectural artifacts, as documented in the DevOps guide.

Frequently Asked Questions

How does Arc-Kit ensure state is always fresh before commands execute?

The arckit-context.mjs hook is registered in hooks.json to fire on every UserPromptSubmit event. It runs synchronously (without the async flag) so the JSON inventory is built and injected into the model's context in the same turn as the user prompt, guaranteeing commands see the latest repository state.

What happens if my repository is too large for the 50KB context limit?

According to the ArcKit book documentation, the arckit-context.mjs hook was specifically optimized to stay under Claude's approximately 50KB output limit. The hook implements size management strategies to ensure that even large repositories with many projects, artifacts, and policies can be represented within the constrained context window.

Can custom commands access the project state built by the hook?

Yes. Any command can reference the projectState object that the hook injects into the model's context. Instead of scanning the filesystem, commands iterate over projectState.projects, projectState.external, or other properties to query repository structure. This approach eliminates I/O overhead and ensures consistency with the state used by built-in commands like /arckit.devops.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}