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

> Discover the purpose and location of opencode.json in the blader/humanizer repository. Learn how this file configures the OpenCode agent framework for permissions, tool access, and LLM routing.

- Repository: [Siqi Chen/humanizer](https://github.com/blader/humanizer)
- Tags: architecture
- Published: 2026-09-12

---

**The [`opencode.json`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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:

```python
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:

```python

# 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:

```python
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`](https://github.com/blader/humanizer/blob/main/opencode.json) directly enable the corresponding tool calls while respecting the defined security boundaries.

## Integration with Repository Architecture

The [`opencode.json`](https://github.com/blader/humanizer/blob/main/opencode.json) file operates as the central policy descriptor within a broader ecosystem of configuration files. It works in conjunction with:

- **[`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)** – Contains the core human-text-analysis logic that the agent generates and processes
- **[`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml)** – Provides metadata for OpenAI-compatible agents loading the skill
- **[`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/opencode.json) serves as the gatekeeper, determining exactly how external AI agents may interact with the Humanizer codebase.

## Summary

- **Location**: [`opencode.json`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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.