What Is opencode.json? Configuration and Placement in the Humanizer Repository

The opencode.json file at the repository root serves as the central configuration descriptor for the OpenCode agent framework, governing permissions, tool access, and LLM routing within the blader/humanizer codebase.

This JSON configuration acts as the operational gateway for AI agents interacting with the repository. Located at the root of the blader/humanizer project, it defines exactly what an automated analysis tool may read, which commands it can execute, and which language models power its reasoning.

Repository Placement and Automatic Discovery

The opencode.json file resides at the absolute root of the repository structure. This specific placement allows the OpenCode runtime to automatically discover and load the configuration without requiring explicit path arguments or environment variables.

Because the file sits at the repository root, the OpenCode agent treats the entire directory as a single accessible "skill" package. This positioning signals that any agent operating on this codebase should reference the permissions and constraints defined within this specific descriptor, enabling seamless integration with tools like Instagit for automated analysis.

Core Configuration Responsibilities

The file functions as a policy engine with four primary technical domains: schema validation, security permissions, tool enablement, and model orchestration.

Schema Declaration and Validation

Every opencode.json begins with a strict $schema reference pointing to https://opencode.ai/config.json. This declaration validates the configuration against the official OpenCode specification, ensuring that permission blocks, tool arrays, and provider settings conform to expected structure before the agent initializes.

Permission Model and Security Boundaries

The permission system implements a default-deny security posture. The configuration explicitly sets "*": "deny" as the baseline policy, meaning all actions are blocked unless specifically whitelisted.

Access is granted only through precise path allowances. The Humanizer configuration uniquely permits read-only access to the repository's cache directory via the pattern /cache/repos/github.com/blader/humanizer/main/**. This restriction prevents the agent from writing files, executing bash commands, or traversing external directories while allowing full read access to the local codebase.

Tool Enablement

The configuration whitelists specific agent capabilities through the permission block. The Humanizer repository enables four core tools:

• grep – Pattern searching across file contents
• glob – File path matching and directory listing
• list – Directory structure enumeration
• lsp – Language server protocol features for code intelligence

These enablements allow the agent to search for TODO comments, enumerate Markdown files, and perform semantic code analysis within the boundaries defined by the permission model.

Model Selection and Provider Configuration

The model field specifies the primary LLM as openrouter/openai/gpt-oss-120b, with a designated small_model fallback of openrouter/qwen/qwen3-32b. This dual-model approach ensures that complex reasoning tasks use the primary high-capacity model while simpler operations can route to the smaller, faster alternative.

Under the provider section, custom HTTP headers identify the calling application as Instagit and define provider fallback ordering (Fireworks → Cerebras). This routing logic ensures reliable model resolution across multiple backend services, preventing analysis interruptions if a primary provider becomes unavailable.

Practical Access and Usage Examples

You can interact with the constraints and capabilities defined in opencode.json programmatically. The following examples demonstrate how to access the configuration and utilize the enabled tools within the permission boundaries.

To load and inspect the configuration directly:

import json, pathlib

config_path = pathlib.Path(__file__).parent.parent / "opencode.json"
with config_path.open() as f:
    cfg = json.load(f)

print("Enabled tools:", [t for t, v in cfg["permission"]["*"].items() if v == "allow"])

To list all Markdown files using the whitelisted glob tool:

# Assuming the agent has access to the `glob` tool

files = glob({"pattern": "**/*.md"})
for f in files:
    print(f)

To search for TODO comments using the permitted grep functionality:

matches = grep({"pattern": "TODO", "include": "*.md"})
for path, line in matches:
    print(f"{path}:{line}")

These snippets illustrate how the permissions declared in opencode.json directly enable the corresponding tool calls while respecting the defined security boundaries.

Integration with Repository Architecture

The opencode.json file operates as the central policy descriptor within a broader ecosystem of configuration files. It works in conjunction with:

• SKILL.md – Contains the core human-text-analysis logic that the agent generates and processes
• agents/openai.yaml – Provides metadata for OpenAI-compatible agents loading the skill
• scripts/validate-package.py – Validates that the skill package structure conforms to requirements defined in the configuration

Together, these files establish a secure, automated pipeline where opencode.json serves as the gatekeeper, determining exactly how external AI agents may interact with the Humanizer codebase.

Summary

• Location: opencode.json resides at the repository root for automatic OpenCode runtime discovery.
• Security Model: Implements default-deny permissions with explicit read-only access to /cache/repos/github.com/blader/humanizer/main/**.
• Enabled Tools: Explicitly whitelists grep, glob, list, and lsp for code analysis operations.
• Model Routing: Configures openrouter/openai/gpt-oss-120b as primary with openrouter/qwen/qwen3-32b fallback, including provider failover logic for Instagit integration.
• Schema Compliance: Validates against https://opencode.ai/config.json to ensure configuration integrity.

Frequently Asked Questions

What is the primary purpose of opencode.json in the Humanizer repository?

The file functions as the configuration descriptor for the OpenCode agent framework, defining the operational boundaries, tool permissions, and LLM routing parameters that govern how automated analysis tools interact with the codebase. It effectively serves as the security and capability policy for AI-driven code analysis.

Where is opencode.json located and how does OpenCode discover it?

The file is located at the absolute root of the blader/humanizer repository. The OpenCode runtime automatically discovers the configuration by scanning for opencode.json in the repository root directory, eliminating the need for manual path specification or environment variable configuration when initializing the agent.

Which specific tools are enabled in the Humanizer opencode.json configuration?

The configuration explicitly enables four analytical tools: grep for pattern matching, glob for file enumeration, list for directory traversal, and lsp for language server features. These tools are whitelisted within the permission block while all other potential actions remain denied by default.

How does the permission model in opencode.json restrict agent actions?

The permission model employs a default-deny approach where "*": "deny" blocks all operations unless explicitly allowed. The Humanizer configuration specifically permits read-only access only to files within /cache/repos/github.com/blader/humanizer/main/**, preventing write operations, bash execution, or access to external system directories while maintaining full codebase readability for analysis.

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