README.md

Ref: main   Size: 3.6 KiB

# claudealong

Write a comment in your code, save the file. A Claude Code session watching the project sees the comment, does the work, and removes the marker. No switching windows, no copy-paste.

## What it does

Write `// @claude write a test for foo` anywhere in a source file and save. The `filewatch-mcp` server detects the marker, emits a `<channel>` block to Claude Code containing the file path, line number, and your ask. Claude reads the file, does the work, and removes the marked line. To prevent the same marker from firing again on subsequent saves, the watcher stamps it inline with a short tag — `[fw-XXXXXXXX]` (8 hex chars) — the first time it is seen. Claude strips the entire tagged line as part of handling the request.

Before:

```go
// @claude write a table-driven test for the Reverse function
func Reverse(s string) string {
```

After Claude has acted (the marker line is removed and the test is written):

```go
func Reverse(s string) string {
```

If Claude only needed to answer a question (no file change), it removes the marker line and replies in the session.

## Install

```bash
go install github.com/xanderle/claudealong/cmd/filewatch-mcp@latest
```

For local development:

```bash
git clone https://github.com/xanderle/claudealong
cd claudealong
make install
```

## Configure

1. Copy `.mcp.json` from this repo to the root of any project where you want `@claude` markers.

2. Start Claude Code with channels enabled:

   ```bash
   claude --dangerously-load-development-channels server:filewatch
   ```

   Once Anthropic approves the channel for general distribution, `--channels` will work instead.

## Supported languages

| Comment style | Extensions / filenames |
|---|---|
| `//` | Go, JavaScript, TypeScript, JSX, TSX, C, C++, Rust, Java, Kotlin, Swift, Scala, C# |
| `#` | Python, Ruby, Shell (sh/bash/zsh), YAML, TOML, Makefile, Dockerfile |
| `--` | SQL, Lua, Haskell, Elm |
| `/* ... */` (single-line) | CSS |
| `<!-- ... -->` (single-line) | HTML, XML, Markdown |

Files with other extensions are skipped silently. Block-comment markers (`/* */`, `<!-- -->`) must fit on one line in v1.

## How dedupe works

When the watcher first sees `@claude ...` in a file, it rewrites that line in place, splicing in a `[fw-XXXXXXXX]` tag:

```
// @claude[fw-3a9f12bc] write a test for foo
```

Tagged markers are never re-emitted. Claude removes the entire tagged line as part of handling the ask, so your file ends up clean.

If the watcher and your editor write to the file at the same instant (mtime conflict), the rewrite is aborted cleanly. The marker stays untagged and will be picked up on the next save.

### Editor behavior on watcher rewrites

The watcher edits your file to insert the tag. Most editors handle this gracefully:

- **VS Code, Vim (`set autoread`):** auto-reload, no friction.
- **JetBrains IDEs:** prompt on external change — accept the reload.
- **Other editors:** check whether they auto-reload or prompt on external modifications.

## Limitations (v1)

- Single-line markers only. Multi-line block comments are not supported.
- One project per Claude Code session. Running two sessions against the same directory will produce duplicate channel notifications.
- Linux and macOS. Windows is untested.
- Hard-excluded paths: `.git/`, `node_modules/`, `dist/`, `build/`, `target/`, `.venv/`. Excluded suffixes: `.swp`, `.tmp`, `.lock`. Everything in `.gitignore` is also excluded.

## Flags

- `--root <path>` — directory to watch (default: `.`).
- `--debounce <duration>` — trailing-edge debounce per file (default: `500ms`). JetBrains autosave bursts may need a longer value, e.g. `--debounce 1s`.