Metadata-Version: 2.4
Name: make-vibe
Version: 0.1.2
Summary: Template-based MCP server for remote job execution
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp
Requires-Dist: remotemanager
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"

# Make-Vibe

This project is designed to allow an AI coding agent to tune a code while 
performing performance experiments on a remote HPC system. You will be
able to edit and develop code locally in a vibe coding tool while compiling
and running on remotely. This includes support for doing the execution on
multiple nodes.

## How It Works

* Prepare the code you would like to work on with an associated Makefile.
* Prepare a template for a jobscript on your remote machine.
* An MCP server is dynamically generated from your Makefile and exposes
the targets to your local LLM.
* BATCH mode: Every time a tool call is made, the code is synchronized to the
remote machine, a jobscript is generated and submitted, and the results of the 
jobscript are returned to the LLM.
* PERSISTENT mode: Jobs are submitted to a preallocated compute node.
* LOCAL mode: commands executed on the same computer as the vibe coding tool.

## Quick Start

```bash
# Install
pip install -e .
```

The `example/` includes:
* `nbody` - turn a naive n-body code into an openmp parallel and optimized code.
* `matmul` - optimize the compiler flags for a matrix multiplication code.
* `heat1d` - MPI porting of a heat flow calculation.

## Key Features

* Automatic tool generation - Parses your Makefile, creates MCP tools for each
target.
* Remote execution - Built on
[remotemanager](https://l_sim.gitlab.io/remotemanager/) for job submission
* Resource control - Specify MPI/OMP parameters per execution
* Build / run variables - Pass compiler flags and other env vars
(e.g., `cflags="-O3"`)

## Main Components

Makefile Target Definition:
```
...
# @env: CFLAGS - Compiler flags      ← Becomes MCP tool parameter
build:                               ← Becomes tool name: make_build
    $(CC) $(CFLAGS) -o app app.c     ← Actual command
...
```

Jobscript template:
```
...
#SBATCH --cpus-per-task=#OMP:default=1#      ← Becomes MCP tool parameter
#SBATCH --ntasks=1
module load system/fx700 FJSVstclanga/1.0.30.01
export OMP_NUM_THREADS=${SLURM_CPUS_PER_TASK}
```

Template Configuration:
```
{
  ...
  "submitter": "sbatch",                          ← Jobscript submitter
  "template_params": {"MPI": "How many mpi..."},  ← Becomes tool parameters
  "template_file": "fx700.sh"                     ← Job script template file
  ...
}
```

## Run Modes

The code can run in three different modes. PERSISTENT and BATCH are the
modes this tool accomplishes. LOCAL could be useful if you want to enforce
some fixed behavior / environment setting procedures for an LLM.

```
┌───────────────────────────────────────────────────────────────────────────┐
│          LOCAL: Developer's Machine (Claude Code + MCP Server)            │
│                                                                           │
│          ┌──────────────┐         ┌─────────────────┐                     │
│          │  Makefile    │────────>│   make-vibe     │                     │
│          │  (targets)   │  parsed │   MCP Server    │                     │
│          │              │         │                 │                     │
│          │ • build      │         │  Auto-generates │                     │
│          │ • run        │         │  MCP tools from │                     │
│          │ • run-large  │         │  targets        │                     │
│          └──────────────┘         └─────────────────┘                     │
│                 +                          |                              │
│          ┌──────────────┐                  |                              │
│          │  Template    │                  v                              │
│          │  config.json │         ┌─────────────────┐                     │
│          │  template.sh │────────>│  Tool Call      │                     │
│          │              │         │  + Parameters   │                     │
│          │ • host       │  fills  │  (MPI=4, etc.)  │                     │
│          │ • submitter  │  params └─────────────────┘                     │
│          │ • parameters │                  |                              │
│          └──────────────┘                  | + rsync                      │
└────────────────────────────────────|──────────────────────────────────────┘
                                     |
              ┌──────────────────────┼────────────────────────┐
              |                      |                        |
              v                      v                        v

┌──────────────────────┐  ┌──────────────────────┐  ┌──────────────────────┐
│  MODE 1: LOCAL       │  │  MODE 2: PERSISTENT  │  │  MODE 3: BATCH       │
│  submitter: "bash"   │  │  submitter: "srun    │  │  submitter: "sbatch" │
│                      │  │    --jobid=XXX bash" │  │                      │
├──────────────────────┤  ├──────────────────────┤  ├──────────────────────┤
│                      │  │                      │  │                      │
│  ┌────────────────┐  │  │  ┌────────────────┐  │  │  ┌────────────────┐  │
│  │ Local Machine  │  │  │  │ Pre-allocated  │  │  │  │  Job Queue     │  │
│  │                │  │  │  │ Compute Node   │  │  │  │                │  │
│  │  Execute       │  │  │  │                │  │  │  │ Job 1→[SLURM]  │  │
│  │  directly      │  │  │  │  [Active job]  │  │  │  │ Job 2→[SLURM]  │  │
│  │                │  │  │  │   Submit to    │  │  │  │ Job 3→[SLURM]  │  │
│  │  bash script   │  │  │  │   this job     │  │  │  │                │  │
│  │                │  │  │  │                │  │  │  │  [Each call =  │  │
│  └────────────────┘  │  │  │ [Job keeps     │  │  │  │  New job]      │  │
│                      │  │  │  running]      │  │  │  │                │  │
│                      │  │  └────────────────┘  │  │  └────────────────┘  │
├──────────────────────┤  ├──────────────────────┤  ├──────────────────────┤
│ ✓ No queue           │  │ ✓ No queue wait      │  │ ✓ Fair scheduling    │
│ ✓ Low latency        │  │ ✓ Rapid iteration    │  │ ✓ Long runs          │
│ ✓ Good for testing   │  │ ✓ Interactive feel   │  │ ✓ Independent runs   │
│                      │  │                      │  │ ✓ Cluster policies   │
│ ✗ Fixed resources    │  │ ✗ Must pre-allocate  │  │                      │
│ ✗ Must run vibe tool │  │ ✗ Fixed resource     │  │ ✗ Queue delays       │
│   on a compute node  │  │ ✗ size (#nodes)      │  │ ✗ Slower iteration   │
└──────────────────────┘  └──────────────────────┘  └──────────────────────┘
```
