Mainline/AGENTS.md

Agent Development Guide

Development Environment

This project uses:

• mise (mise.jdx.dev) - tool version manager and task runner
• hk (hk.jdx.dev) - git hook manager
• uv - fast Python package installer
• ruff - linter and formatter
• pytest - test runner

Setup

# Install dependencies
mise run install

# Or equivalently:
uv sync

Available Commands

mise run test       # Run tests
mise run test-v     # Run tests verbose
mise run test-cov   # Run tests with coverage report
mise run lint       # Run ruff linter
mise run lint-fix   # Run ruff with auto-fix
mise run format     # Run ruff formatter
mise run ci         # Full CI pipeline (sync + test + coverage)

Git Hooks

At the start of every agent session, verify hooks are installed:

ls -la .git/hooks/pre-commit

If hooks are not installed, install them with:

hk init --mise
mise run pre-commit

The project uses hk configured in hk.pkl:

• pre-commit: runs ruff-format and ruff (with auto-fix)
• pre-push: runs ruff check

Workflow Rules

Before Committing

1. Always run the test suite - never commit code that fails tests:

   mise run test
   

2. Always run the linter:

   mise run lint
   

3. Fix any lint errors before committing (or let the pre-commit hook handle it).

4. Review your changes using git diff to understand what will be committed.

On Failing Tests

When tests fail, determine whether it's an out-of-date test or a correctly failing test:

• Out-of-date test: The test was written for old behavior that has legitimately changed. Update the test to match the new expected behavior.

• Correctly failing test: The test correctly identifies a broken contract. Fix the implementation, not the test.

Never modify a test to make it pass without understanding why it failed.

Code Review

Before committing significant changes:

• Run git diff to review all changes
• Ensure new code follows existing patterns in the codebase
• Check that type hints are added for new functions
• Verify that tests exist for new functionality

Testing

Tests live in tests/ and follow the pattern test_*.py.

Run all tests:

mise run test

Run with coverage:

mise run test-cov

The project uses pytest with strict marker enforcement. Test configuration is in pyproject.toml under [tool.pytest.ini_options].

Architecture Notes

• ntfy.py and mic.py are standalone modules with zero internal dependencies
• eventbus.py provides thread-safe event publishing for decoupled communication
• controller.py coordinates ntfy/mic monitoring
• The render pipeline: fetch → render → effects → scroll → terminal output

Effects Plugin System

The effects system is implemented as a plugin architecture in engine/effects/.

Core Components

Module	Purpose
effects/types.py	EffectConfig, EffectContext dataclasses and EffectPlugin protocol
effects/registry.py	Plugin discovery and management (EffectRegistry)
effects/chain.py	Ordered pipeline execution (EffectChain)
effects_plugins/*.py	Externalized effect plugins

Creating a New Effect

Create a file in effects_plugins/ with a class ending in Effect:

from engine.effects.types import EffectConfig, EffectContext

class MyEffect:
    name = "myeffect"
    config = EffectConfig(enabled=True, intensity=1.0)
    
    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
        # Process buffer and return modified buffer
        return buf
    
    def configure(self, config: EffectConfig) -> None:
        self.config = config

NTFY Commands

Send messages to the ntfy topic to control effects:

/effects list
/effects noise on
/effects noise off
/effects noise intensity 0.5
/effects reorder noise,glitch,fade,firehose

Conventional Commits

Commit messages follow the Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

• feat: A new feature
• fix: A bug fix
• docs: Documentation only changes
• style: Changes that don't affect code meaning (formatting)
• refactor: Code change that neither fixes a bug nor adds a feature
• test: Adding or updating tests
• chore: Changes to build process, dependencies, etc.

Examples

feat(effects): add plugin architecture for visual effects
fix(layers): resolve glitch effect not applying on empty buffer
docs(AGENTS.md): add effects plugin system documentation
test(effects): add tests for EffectChain pipeline ordering