How kmosoti/blackcell works
1. Overall shape
BlackCell is a Python CLI/application that models a repository, derives typed facts from it, reasons with symbolic constraints, and then plans or runs agent work through interchangeable runtimes. The architecture is intentionally modular: observation, reasoning, planning, runtime execution, and trace capture are separated into distinct packages.
2. Primary entry points
The user-facing entry point is the blackcell CLI in src/blackcell/cli/app.py, with output formatting in src/blackcell/cli/output.py. The README’s commands (world observe, nesy validate, harness plan, harness run) map to these subsystems, so the CLI is the top-level orchestration layer.
3. Configuration and environment
Repository behavior is driven by configuration loaders in src/blackcell/config, backed by blackcell.toml, blackcell.plan.yaml, and environment handling in src/blackcell/config/env.py. This is the boundary where repo-specific settings, runtime selection, and workflow parameters are normalized before entering the rest of the system.
4. World-model subsystem
src/blackcell/world is the repository-understanding layer. Its job is to hold the typed representation of the repo’s current state, likely derived from files, docs, and other observed signals. In the README’s framing, this is where “evidence” becomes a compact internal model.
5. NeSy reasoning subsystem
src/blackcell/nesy implements the lightweight symbolic reasoning layer. It sits on top of the world model and works with typed facts and rules rather than a heavy ML stack. This is the layer that turns observed state into beliefs, constraints, or validations that can influence planning.
6. Planning and execution harness
src/blackcell/harness is the runtime-agnostic execution boundary. It appears to own the planning and run lifecycle: producing an execution plan, then dispatching work into whichever runtime adapter is selected. This is the main “do work” boundary between internal reasoning and external execution.
7. Runtime adapters
src/blackcell/runtime abstracts how work is actually executed, and src/blackcell/runtime/service.py suggests a service layer around adapter selection and invocation. The README’s emphasis on interchangeable runtimes means this package is a key architectural seam: the planning layer stays stable while execution backends can vary.
8. Agent model and registry
src/blackcell/agents defines the agent-facing abstractions and metadata. models.py, registry.py, and opencode.py indicate support for multiple agent definitions and integration with specific agent ecosystems. This package is where agent capabilities are described and resolved before being rendered into workflows.
9. Control plane
src/blackcell/control_plane is the highest-level orchestration domain beyond the CLI. It includes loading, validation, schema/model definitions, rendering, sync, Git integration, project fields, capability handling, PR support, and codex CLI integration. This package is likely responsible for turning repository state plus configuration into actionable agent workflows and synchronizing those workflows with external systems.
10. External integrations
The main external boundary is GitHub, exposed through src/blackcell/providers/github.py and its registry. The generated cache generated/cache/github_graphql_capabilities.json and the script scripts/github_graphql_capabilities.py indicate a data-refresh path for API capability discovery. This is important for architecture because part of the system depends on external GitHub metadata rather than only local repo files.
11. Traceability and state change tracking
The README emphasizes explicit traces, surprises, and revisions; those concerns are reflected across world, harness, vanguard, and control_plane. src/blackcell/vanguard appears to model change specifications and state transitions, which likely serve as the repository’s audit/change tracking layer feeding back into the world model and planning decisions.
12. Documentation and research as first-class artifacts
The docs/ tree is unusually rich and functionally important: it defines the conceptual model (world-model, nesy, harness, runtime-adapters), architectural decisions, glossary, and target environments (codex-cli, containers, opencode). This suggests the repo’s architecture is partly encoded as living documentation, not just code.
13. Test structure
tests/unit mirrors the major packages and validates them in isolation: agents, config, control plane, harness, runtime adapters, world model, NeSy, Vanguard, GitHub provider, and CLI behavior. That test layout reinforces the boundaries of the system and indicates the intended dependency direction: lower-level models/services are tested separately from CLI wiring.
14. Deployment and development environment
The repository is container-aware (Containerfile, compose.yaml, .devcontainer/) and pinned to a Python toolchain (pyproject.toml, uv.lock, .python-version). This matters architecturally because the project is designed to run consistently in local CLI, devcontainer, and containerized contexts, which aligns with the runtime-agnostic harness goal.
15. Data flow in one line
The core flow is: repository and configuration are observed, observations are converted into typed world facts, NeSy rules refine those facts into beliefs/constraints, the harness turns those into plans, runtime adapters execute the plan, and traces feed back into the world/control-plane layers for revision and synchronization.
Main entry points: app.py CLI app · facade.py Control facade · harness/service.py Harness · world/service.py World service
Components 24
CLI & config
User entrypoints and repository/runtime configuration.
- CLI app · Top-level blackcell command and subcommand orchestration.
src/blackcell/cli/app.py - Output · Human-readable and structured CLI output helpers.
src/blackcell/cli/output.py - Config loader · Loads repository settings and normalizes workflow/runtime configuration.
src/blackcell/config/loader.py - Config models · Typed configuration and environment models.
src/blackcell/config/models.py - Env · Environment-variable and process-context handling.
src/blackcell/config/env.py
Core model
Repository state, symbolic reasoning, and change tracking.
- World service · Builds and updates the typed repository world model from observations.
src/blackcell/world/service.py - World facts · Typed facts and repository-state structures.
src/blackcell/world/models.py - NeSy service · Applies rules and constraints over the world model.
src/blackcell/nesy/service.py - NeSy model · Symbolic reasoning inputs and outputs.
src/blackcell/nesy/models.py - Change spec · Describes revisions, surprises, and tracked state transitions.
src/blackcell/vanguard/changespec.py
Planning & execution
Planning, runtime dispatch, and agent abstraction.
- Harness · Creates plans and coordinates execution lifecycle.
src/blackcell/harness/service.py - Plan model · Execution-plan and harness data structures.
src/blackcell/harness/models.py - Runtime service · Selects and invokes interchangeable runtime backends.
src/blackcell/runtime/service.py - Runtime model · Runtime adapter interfaces and execution records.
src/blackcell/runtime/models.py - Agent registry · Resolves agent definitions and capabilities.
src/blackcell/agents/registry.py - Agent models · Agent metadata and capability structures.
src/blackcell/agents/models.py
Control plane
Workflow assembly, rendering, validation, sync, and external capability handling.
- Control facade · High-level control plane entry that stitches workflow pieces together.
src/blackcell/control_plane/facade.py - Workflow · Builds agent workflows from repo state and configuration.
src/blackcell/control_plane/agent_workflow.py - Rendering · Renders agents, workflows, and control-plane artifacts.
src/blackcell/control_plane/rendering.py - Validation · Validates control-plane inputs and generated artifacts.
src/blackcell/control_plane/validation.py - Sync · Synchronizes generated control-plane state back to the repository and Git context.
src/blackcell/control_plane/sync.py - Capabilities · Tracks supported capabilities and external feature discovery.
src/blackcell/control_plane/capabilities.py
Integrations
External provider and generated capability data.
- GitHub provider · GitHub-backed provider implementation and API boundary.
src/blackcell/providers/github.py - Caps cache · Cached GitHub GraphQL capability data used by control-plane discovery.
generated/cache/github_graphql_capabilities.json
Connections 28
- CLI app → Config loader: loads · CLI boots from repository and runtime configuration.
- CLI app → World service: observes · User commands can derive the repository world model.
- CLI app → NeSy service: validates · CLI exposes symbolic validation flows.
- CLI app → Harness: plans/runs · CLI drives planning and execution workflows.
- CLI app → Control facade: orchestrates · CLI can enter the control-plane workflow stack.
- CLI app → Output: formats · Output rendering is separated from command logic.
- Config loader → Config models: produces · Parsed configuration is normalized into typed models.
- Config loader → Env: reads · Configuration is influenced by environment context.
- World service → World facts: stores · World service populates the repository state model.
- World service → Change spec: tracks · State changes and surprises feed revision tracking.
- World service → NeSy service: feeds · World facts are the input to symbolic reasoning.
- NeSy service → NeSy model: uses · Reasoning operates over typed facts and constraints.
- NeSy service → Harness: influences · Reasoning output shapes the plan and execution decisions.
- Harness → Plan model: builds · Harness creates execution plans and lifecycle state.
- Harness → Runtime service: dispatches · Planned work is handed to a selected runtime backend.
- Runtime service → Runtime model: implements · Runtime service conforms to adapter contracts.
- Agent registry → Agent models: resolves · Agent registry is backed by typed agent definitions.
- Control facade → Workflow: assembles · Facade coordinates workflow construction.
- Control facade → Rendering: renders · Facade produces control-plane artifacts.
- Control facade → Validation: checks · Facade validates generated state and inputs.
- Control facade → Sync: syncs · Facade coordinates synchronization of generated artifacts.
- Workflow → Agent registry: selects · Workflows resolve agent implementations through the registry.
- Workflow → Harness: plans · Workflow output is executed through the harness.
- Rendering → Agent models: formats · Rendering turns agent metadata into executable artifacts.
- Validation → Config models: applies · Validation enforces repository and workflow configuration.
- Sync → GitHub provider: uses · Sync integrates with GitHub-backed repository services.
- Capabilities → GitHub provider: discovers · Capabilities are derived from provider support.
- Capabilities → Caps cache: reads · Capability discovery uses generated cached metadata.