Introduction

Clamshell allows you to define tasks in a human-readable format and execute them with automatic handling of dependencies, execution order, and optional status checks. Ideal for build pipelines, deployment workflows, and batch operations.

Installation

Clamshell is available as a CLI tool or as a desktop application.

CLI

  • mac
  • linux
  • win
brew install clam
apt-get install clam
gem install clam

Desktop

  • mac
  • linux
  • win
link
N/A
link

Usage

$ clam.sh [config-file]

Global Config

Learn how to configure settings for Scribbler, such as your syntax highlighting preference and the default saving folder location.

Key Description Default
log_file Path to output log file "./logfile.log"
silent Suppress stdout/stderr printing false
debug_mode Enable debug output and graphing false

Task Properties

Learn how to configure settings for Scribbler, such as your syntax highlighting preference and the default saving folder location.

Key Description Requred
command Shell command to execute Yes
dependencies Comma-separated task names that must complete before this one No
status_check Optional shell command that returns 0 on success No
order Number indicating run order. Same order = run in parallel No

Execution Engine

  • Tasks only run after all their dependencies have completed successfully
  • Circular dependencies are automatically detected and reported
  • Dependencies are transitive - if A depends on B and B depends on C, then A implicitly depends on C
  1. Tasks are grouped and sorted by their order value.
  2. Tasks with the same order run in parallel.
  3. Tasks wait for dependencies to complete successfully.
  4. If a task fails (command or status_check returns non-zero), execution halts.

Best Practices

Use Status Checks

Validate output to avoid false positives.

Leave gaps in orders

Use `10, 20, 30` to allow future task insertions.

Parallelize cautiously

Be mindful of shared resources.

Use Debug mode

See `clamshell_ast.txt` for a visual task graph.

Parallel Execution

  • Tasks with the same order value run in parallel
  • Be careful with resource contention when running tasks in parallel
  • For high-performance systems, group CPU-intensive tasks with I/O-intensive tasks

Error Handling

  • If a task fails, all dependent tasks are skipped
  • Use status_check to verify that tasks completed as expected
  • Log files provide detailed information about what went wrong

Debugging

When debug_mode=true, Clamshell generates:

  • clamshell_ast.txt: Shows parsed task tree and execution order
  • Task execution logs (stdout/stderr or from log_file)

Configuration Files

Clamshell uses an INI-style configuration format where each `[task]` section defines a task to run.
Sample .clamsh configuration:

# Global config (optional)
log_file=./clamshell.log
silent=false
debug_mode=true

# Task definitions
[prepare]
command=mkdir -p ./output
status_check=test -d ./output
order=10

[compile]
command=make all
dependencies=prepare
order=20

[test]
command=make test
dependencies=compile
order=30

[deploy]
command=make deploy
dependencies=test
order=40

Examples

You can find examples in the examples/ directory (if bundled), including:

  • Simple build pipelines
  • Tasks with conditional execution
  • Parallel frontend/backend builds
  • Real-world deployment scenarios