Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,24 @@ AgentExperience.NET is a **preview**. It is not production ready, and public API

## Unreleased

### Added

- **`aexp init [--print] [--force] [--verify <json array>]`** writes a commented `.aexp/config.json` from one command,
run in the project root, with no agent named: the verifier detected when one kind of project is at the root
(`dotnet test`, `npm test`, `pytest`, `go test ./...`; and now `make test`, for a `Makefile` with a `test:` target,
proposed only when none of those fits),
asked for at a terminal when none or several fit (a candidate's number, a JSON array, or Enter for the placeholder),
or given with `--verify` as a JSON array (never a shell line, never split on spaces). It adds `.aexp/` to
`.gitignore` when the directory is under git, never touches an existing config (`--force` replaces it, revoking its
trust like any edit), and prints the steps left to a person: `aexp trust`, then `aexp setup claude-code` or
`claude mcp add`. It approves nothing. `aexp setup claude-code` writes its config and `.gitignore` entry through the
same generator (`ProjectInit`), so there is one. See [CLI and MCP](docs/guide/cli-and-mcp.md#write-it-aexp-init).

### Changed

- The config `aexp setup claude-code` writes carries a `//` comment on each choice, as `aexp init`'s does; the loader
has always skipped comments. Its values are unchanged.

## 0.1.0-preview.19

This preview adds an experimental, off-by-default reflective execution loop. The same tag releases the eight NuGet packages, the Python distribution and the Go modules at this version, as before.
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,10 +67,12 @@ preview, `0.1.0-preview.19`; until then, [build it from this repository](dogfood

```bash
dotnet tool install --global AgentExperience.Cli --prerelease
aexp init # in the project root: detects the test command, writes .aexp/config.json
aexp trust # after you reviewed the config: a person's step
claude mcp add aexp -- aexp mcp # or any MCP client: the server is `aexp mcp`, run in the project
```

A `.aexp/config.json` in the project names the scope and the one command `aexp` may run, the verifier
`.aexp/config.json` names the scope and the one command `aexp` may run, the verifier
(`"verify": { "command": ["dotnet", "test"] }`, exit code 0 = pass), which runs only once a person has reviewed the
config and approved it with `aexp trust` (an edit revokes the approval). The MCP tools `experience_recall`,
`experience_failure_hint`, `experience_record_call`, `experience_finish` and `experience_lessons` (or the commands
Expand Down
14 changes: 8 additions & 6 deletions docs/guide/claude-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,12 +26,14 @@ aexp trust # after you rev
- **adds the hooks to `.claude/settings.json`**, merged with what is there: every existing hook, matcher and setting is
kept, and an event that already has an `aexp hook` command gets no second one. A settings file that is not plain JSON
(with comments, say) is left alone, and setup tells you to add the block by hand. Running setup again changes nothing.
- **writes `.aexp/config.json`** if there is none (an existing one is never touched), with the identity named after the
directory, the holdout at 20% so the benefit can be measured, `file_path` as the only argument kept from tool calls, and
the verifier detected from the project when it is obvious: `dotnet test` (a solution or project file at the root),
`npm test` (a `package.json` with a test script), `pytest` (`pyproject.toml`, `pytest.ini`, `conftest.py`, `tox.ini`)
or `go test ./...` (`go.mod`). When none or several match, it writes a placeholder that refuses to run until you set
`verify.command`.
- **writes `.aexp/config.json`** if there is none (an existing one is never touched), through the same generator as
[`aexp init`](cli-and-mcp.md#write-it-aexp-init): the identity named after the directory with `"agent": "claude-code"`,
the holdout at 20% so the benefit can be measured, `file_path` as the only argument kept from tool calls, a comment on
each choice, and the verifier detected from the project when it is obvious: `dotnet test` (a solution or project file
at the root), `npm test` (a `package.json` with a test script), `pytest` (`pyproject.toml`, `pytest.ini`,
`conftest.py`, `tox.ini`) or `go test ./...` (`go.mod`), and `make test` (a `Makefile` with a `test:` target) only when
none of those fits. When none or several match, it writes a placeholder that refuses to run until you set `verify.command` (setup asks nothing; run
`aexp init` first to choose from the candidates or pass `--verify`).
- **adds `.aexp/` to `.gitignore`**: the store, open runs, sessions, the hook log and the config stay local.
- **prints the next steps**, including the permission rules below. It never approves the config.

Expand Down
28 changes: 27 additions & 1 deletion docs/guide/cli-and-mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ the [injection holdout](injection.md), the [lessons view](deployment.md#seeing-w
```bash
dotnet tool install --global AgentExperience.Cli --prerelease
aexp --version
aexp init # in the project root: writes .aexp/config.json and the .gitignore entry
```

It needs the .NET 10 runtime. The SQLite file is created (owner-only) on first use.
Expand All @@ -26,6 +27,30 @@ file `--config <path>` or the `AEXP_CONFIG` environment variable names. Relative
root, the directory that holds `.aexp/`. The tool refuses to start without a config, without an identity, or without a
verifier, and on Unix it refuses a config (or config directory) another user owns.

### Write it: `aexp init`

`aexp init [--print] [--force] [--verify <json array>]`, run in the project root, writes a commented `.aexp/config.json`
with the defaults below (the SQLite store in `.aexp/`, the identity named after the directory, a 20% holdout, `file_path`
as the only argument kept from tool calls, recall on, a 540 s timeout under the Claude Code Stop hook's 600 s, check
`tests`), adds `.aexp/` to `.gitignore` in that directory when it is under git (a `.gitignore` there, or a `.git` there or
in a directory above it, up to your home directory), and prints the steps left to you: review it, `aexp trust`, then
`aexp setup claude-code` or `claude mcp add`. It never approves the config. The verifier is:

- **detected** when exactly one kind of project is at the root: `dotnet test` (a `.sln`, `.slnx`, `.csproj` or
`.fsproj`), `npm test` (a `package.json` whose `scripts.test` is set), `pytest` (`pyproject.toml`, `pytest.ini`,
`conftest.py` or `tox.ini`) or `go test ./...` (`go.mod`); when none of those fits, `make test` (a `Makefile` with a
`test:` target);
- **asked for** when none or several match and you are at a terminal: a number from the list of candidates, a JSON
array, or Enter for a placeholder to set later. A wrong answer is asked again once; then the placeholder. When standard
input is not a terminal, the placeholder is written and the candidates are printed;
- **given** with `--verify '["npm","test","--","--ci"]'`: a JSON array of non-empty strings, never a shell line and
never split on spaces (anything else is a usage error, exit 2).

The placeholder refuses to run until `verify.command` is set. An existing config is never touched (exit 2, naming
`--force`); `--force` replaces it whole, which revokes its `aexp trust` approval like any other edit. `--print` prints the
config and the `.gitignore` line and writes nothing. The file is written atomically, `.aexp/` owner-only (`0700`) and the
config owner read and write. Comments (`//`) are allowed in the config; the loader skips them.

### Approve it: `aexp trust`

A config names a command, so **a config from an untrusted checkout is code execution**. Like direnv, `aexp` runs the
Expand Down Expand Up @@ -138,7 +163,8 @@ aexp finalize --run "$run" # runs the verifier;
| `aexp mcp` | Serves the MCP tools over stdin and stdout. |
| `aexp trust` | Prints what the config would run, and approves the config (see above). |
| `aexp runs prune --older-than <age>` | Deletes open runs (never ended) started longer ago than `7d`, `12h` or `30m`, unless a command is using them, and Claude Code session files not touched for as long. |
| `aexp setup claude-code [--print]` | Adds the Claude Code hooks to `.claude/settings.json`, a default config and the `.gitignore` entry ([Claude Code](claude-code.md)). |
| `aexp init [--print] [--force] [--verify <json array>]` | Writes a commented `.aexp/config.json` with the verifier detected, asked for or given, and the `.gitignore` entry; prints the next steps. Never trusts the config ([above](#write-it-aexp-init)). |
| `aexp setup claude-code [--print]` | Adds the Claude Code hooks to `.claude/settings.json`, the same default config when there is none, and the `.gitignore` entry ([Claude Code](claude-code.md)). |
| `aexp hook <event> [--timeout <s>]` | A Claude Code hook: reads the event's JSON on standard input, prints the hook output; always exits 0 ([Claude Code](claude-code.md)). |

Exit codes: 0 done, 1 failed, 2 a usage error (including a run that is not open), 3 a configuration the tool refuses
Expand Down
27 changes: 21 additions & 6 deletions src/AgentExperience.Cli/AexpCli.cs
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,19 @@

namespace AgentExperience.Cli;

/// <summary>What one invocation of the tool runs with: its streams, working directory, environment and clock.</summary>
/// <summary>
/// What one invocation of the tool runs with: its streams, working directory, environment and clock. <c>ReadLine</c>
/// reads one line a person typed; <see langword="null"/> means standard input is not a terminal, so nothing asks.
/// </summary>
internal sealed record AexpConsole(
TextWriter Out,
TextWriter Error,
string WorkingDirectory,
Func<string, string?> Environment,
TimeProvider Clock,
Stream? StandardInput = null,
Stream? StandardOutput = null);
Stream? StandardOutput = null,
Func<string?>? ReadLine = null);

/// <summary>
/// The <c>aexp</c> command line. Plain parsing, no framework: each command takes named options only, and every value
Expand Down Expand Up @@ -50,6 +54,9 @@ Export lessons measured as helping (to a file, or
aexp mcp Serve the MCP tools over stdio.
aexp trust Show the config's verifier, and approve the config.
aexp runs prune --older-than <age> Delete open runs older than e.g. 7d, 12h, 30m.
aexp init [--print] [--force] [--verify <json array>]
Write .aexp/config.json (verifier detected, asked or
given) and the .gitignore entry; never trusts it.
aexp setup claude-code [--print] Add the Claude Code hooks, a config and .gitignore entry.
aexp hook <event> [--timeout <s>] [--claude-md [file]] [--agents-md [file]]
A Claude Code hook (reads the event JSON on stdin).
Expand Down Expand Up @@ -89,18 +96,26 @@ public static async Task<int> RunAsync(string[] args, AexpConsole console, Cance
return parsed.Command.Count == 0 && !parsed.Flag("help") ? Usage : Ok;
}

// Setup runs before there is a config.
if (parsed.Command is ["setup", ..])
// Init and setup run before there is a config.
if (parsed.Command is ["init", ..] or ["setup", ..])
{
try
{
return await ClaudeCodeSetup.RunAsync(parsed, console, cancellationToken).ConfigureAwait(false);
return parsed.Command[0] == "init"
? await ProjectInit.RunAsync(parsed, console, cancellationToken).ConfigureAwait(false)
: await ClaudeCodeSetup.RunAsync(parsed, console, cancellationToken).ConfigureAwait(false);
}
catch (AexpUsageException ex)
{
await console.Error.WriteLineAsync("aexp: " + ex.Message + (ex.Detail is null ? string.Empty : " (" + ex.Detail + ")")).ConfigureAwait(false);
return Usage;
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
// A write that failed (permissions, a full disk): the type and message only, never a stack trace.
await console.Error.WriteLineAsync($"aexp: failed ({ex.GetType().Name}): {ex.Message}").ConfigureAwait(false);
return Failed;
}
}

AexpSettings settings;
Expand Down Expand Up @@ -332,7 +347,7 @@ internal static TimeSpan ParseAge(string text)
/// <summary>Command words, then <c>--name value</c> options and bare <c>--flag</c>s.</summary>
internal sealed class Arguments
{
private static readonly HashSet<string> Flags = new(StringComparer.Ordinal) { "failure", "all", "help", "version", "print" };
private static readonly HashSet<string> Flags = new(StringComparer.Ordinal) { "failure", "all", "help", "version", "print", "force" };

/// <summary>Options whose value may be left out (the next argument is theirs unless it is another option).</summary>
private static readonly HashSet<string> OptionalValues = new(StringComparer.Ordinal) { "claude-md", "agents-md" };
Expand Down
Loading
Loading