Local Development

Workflow for developing and testing Dexter changes locally.

Environment setup

git clone https://github.com/aakashvarma/dexter.git
cd dexter
 
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
 
export OPENAI_API_KEY=sk-...
export FAL_KEY=...
 
# OpenCode
curl -fsSL https://opencode.ai/install | bash
opencode
/connect

Running the pipeline locally

# Full run
opencode run --agent orchestrator -- "build the dishwasher from input_images/dishwasher.png"
 
# Resume
opencode run --agent orchestrator -- "resume .intermediate/dishwasher/001/"
 
# OpenCode TUI (interactive)
opencode

Testing individual scripts

Scripts can be run independently for debugging, outside the agent loop.

Python scripts

# Validate JSON
python3 tool_scripts/common.py \
  --schema schemas/parts.schema.json \
  --data .intermediate/dishwasher/001/parts.json
 
# Placement init
python3 tool_scripts/initialize_placement.py \
  --run-dir .intermediate/dishwasher/001

Blender scripts

blender --background --python tool_scripts/blender_assemble.py -- \
  --layout .intermediate/dishwasher/001/iterations/006/assembly.json \
  --output /tmp/test_assembled.blend
 
# Open result
blender /tmp/test_assembled.blend

Component generation (costs API credits)

export OPENAI_API_KEY=sk-...
export FAL_KEY=...
python3 tool_scripts/generate_components.py \
  --run-dir .intermediate/dishwasher/001

Developing agent prompts

Edit .opencode/agents/<agent>.md
No restart needed, OpenCode reads prompts at invocation time
Test by invoking the specific step:

# Test analyze agent in isolation
opencode run --agent analyze -- "analyze input_images/dishwasher.png and write parts.json to .intermediate/dishwasher/002/parts.json"
 
# Test full pipeline with your changes
opencode run --agent orchestrator -- "build the dishwasher from input_images/dishwasher.png"

Developing documentation

cd docs
npm install
npm run dev    # http://localhost:3000

Build check:

npm run build  # must pass with 0 errors

Media files go in docs/public/assets/. Reference in MDX:

![alt](/assets/images/dexter/image.png)
 
<video controls width="100%">
  <source src="/assets/video/dexter/video.mp4" type="video/mp4" />
</video>

Iterating on a specific pipeline step

Placement loop only

If one-time steps are complete:

# Delete iterations to redo placement
rm -rf .intermediate/dishwasher/001/iterations/004/
opencode run --agent orchestrator -- "resume .intermediate/dishwasher/001/"

Single iteration manual test

Edit assembly.json manually
Run blender_assemble + render + validate
Inspect renders in iterations/<N>/renders/

ITER=.intermediate/dishwasher/001/iterations/006
 
blender --background --python tool_scripts/blender_assemble.py -- \
  --layout $ITER/assembly.json --output $ITER/assembled.blend
 
blender --background --python tool_scripts/blender_render_views.py -- \
  --blend $ITER/assembled.blend \
  --cameras $ITER/render_views.json \
  --output-dir $ITER/renders/

Bring your own assembly

Write assembly.json by hand, validate, then assemble:

python3 tool_scripts/common.py \
  --schema schemas/assembly.schema.json \
  --data my_assembly.json

Debugging tips

Problem	Debug approach
Wrong scale	Compare `node_scale` and `world_size` in `assembly.json`; check `component_dims.json` raw sizes
Wrong position	Open `assembled.blend`, check pivot empties
Schema failure	Run `common.py` directly, read error paths
Agent ignores instructions	Check prompt file path in `opencode.json`; verify permissions
Step not skipped on resume	Check if output exists AND validates; invalid JSON triggers redo
Blender script fails	Run with `--background` and check stderr; test with GUI: `blender --python script.py`

Config for faster dev iteration

Create a local override mindset in configs/base.yaml:

loop:
  max_loops: 3
render:
  resolution: [1280, 720]
  samples: 32
image_generation:
  quality: "low"

Do not commit dev-only config unless the team agrees.

Linting tool scripts

See Tool Script Standards for layout, naming, CLI, and output conventions. Quick check:

ruff check tool_scripts/
ruff format tool_scripts/

What to verify before submitting changes

python3 tool_scripts/common.py passes on any changed schemas with valid fixtures in test_fixtures/
ruff check tool_scripts/ and ruff format tool_scripts/ pass if scripts changed
Agent prompt changes tested with at least one pipeline step
Tool script changes tested with --help and a real run against .intermediate/ artifacts
npm run build passes in docs/ if documentation changed
AGENTS.md updated if pipeline order or semantics changed

Tool Script Standards