Development Workflow Guide#

See Also:

Local Development - First-time setup and directory structure

Configuration Reference - All configuration options

This guide covers daily development workflows for making changes to Marcus code.

Quick Reference#

Change Type	Action Required	Command
Python code changes	Restart Marcus	`./marcus stop && ./marcus start`
Dependencies (requirements.txt)	Reinstall	`pip install -r requirements.txt`
Config file (config_marcus.json)	Restart Marcus	`./marcus stop && ./marcus start`
Infrastructure (Planka/Postgres)	Recreate containers	`docker compose up -d --force-recreate`

Architecture#

Marcus runs locally on your machine, not in Docker. Docker is only used for infrastructure (Planka + Postgres). This is because agents write to the local filesystem, and running Marcus in Docker would create path mismatches.

Docker:  Planka + Postgres (infrastructure)
Local:   Marcus + Cato + Agents (share the host filesystem)

Detailed Workflows#

1. Python Code Changes (Most Common)#

When you modify Python files in src/:

# Restart Marcus
./marcus stop
./marcus start

2. Dependency Changes#

When you add/remove packages in requirements.txt:

pip install -r requirements.txt
./marcus stop
./marcus start

3. Configuration Changes#

When you edit config_marcus.json:

# Config is read at startup, just restart
./marcus stop
./marcus start

4. Infrastructure Changes#

When you need to reset Planka or Postgres:

# Restart infrastructure
docker compose restart

# Full reset (destroys data)
docker compose down -v
docker compose up -d

Testing Workflow#

Run Tests#

pytest tests/
pytest tests/unit/             # Unit tests only
pytest tests/integration/      # Integration tests only

Linting and Type Checking#

black src/ tests/
isort src/ tests/
mypy src/
pre-commit run --all-files

Common Development Tasks#

View Logs#

# Marcus logs (timestamped files)
tail -f logs/marcus_*.log

# Planka/Postgres logs
docker compose logs -f planka
docker compose logs -f postgres

Reset Infrastructure#

# Stop and remove containers + volumes
docker compose down -v

# Start fresh
docker compose up -d

Check Infrastructure Status#

docker compose ps

Quick Decision Tree#

Made a change?
|-- Python code only?
|   --> Restart Marcus
|
|-- Added/removed packages?
|   --> pip install, then restart Marcus
|
|-- Changed config file?
|   --> Restart Marcus
|
|-- Changed docker-compose.yml?
|   --> docker compose up -d --force-recreate
|
|-- Need fresh Planka data?
    --> docker compose down -v && docker compose up -d

Best Practices#

1. Test Before Committing#

pytest tests/
pre-commit run --all-files

2. Keep Docker Clean#

docker image prune -a           # Remove unused images
docker volume prune             # Remove unused volumes

3. Document Changes#

Update relevant docs
Add tests
Update CHANGELOG.md

For configuration changes, update Configuration Reference