@iinm/plain-agent 1.7.18 → 1.7.20

package/README.md

@@ -1,10 +1,6 @@
-<p align="center">
-  <img src="https://pub-0bb49aa929f242d49c89ed8c297932b5.r2.dev/plain-agent/plain-agent-logo.png" alt="plain-agent logo" width="320">
-</p>
-
 # Plain Agent
 
-A lightweight CLI-based coding agent with zero framework dependencies.
+A lightweight CLI-based coding agent.
 
 ## Why Plain Agent?
 
@@ -23,6 +19,7 @@ A lightweight CLI-based coding agent with zero framework dependencies.
 
 ## Limitations
 
+- **CLI only** — Plain Agent does not provide a terminal UI.
 - **Sequential subagent execution** — Subagents run one at a time rather than
   in parallel. The trade-off is full visibility: every step is streamed to
   your terminal so you can follow exactly what each subagent is doing.
@@ -31,7 +28,7 @@ A lightweight CLI-based coding agent with zero framework dependencies.
 
 - Node.js 22 or later
 - LLM provider credentials
-- bash / docker for sandboxed execution
+- Bash / Docker for sandboxed execution
 - [ripgrep](https://github.com/burntsushi/ripgrep)
 - [fd](https://github.com/sharkdp/fd)
 
@@ -52,8 +49,8 @@ Create the configuration.
 ```js
 // ~/.config/plain-agent/config.local.json
 {
-  "model": "gpt-5.4+thinking-high",
-  // "model": "claude-sonnet-4-6+thinking-high",
+  "model": "claude-sonnet-4-6+thinking-high",
+  // "model": "gpt-5.5+thinking-high",
 
   // Configure the providers you want to use
   "platforms": [
@@ -83,15 +80,11 @@ Create the configuration.
       "provider": "gemini",
       "apiKey": "<GEMINI_API_KEY>",
       "model": "gemini-3-flash-preview"
-      // Optional
-      // "baseURL": "<proxy_url>"
 
       // Or use Vertex AI (Requires gcloud CLI to get authentication token)
       // "provider": "gemini-vertex-ai",
       // "baseURL": "https://aiplatform.googleapis.com/v1beta1/projects/<project_id>/locations/<location>",
       // "model": "gemini-3-flash-preview"
-      // Optional:
-      // "account": "<service_account_email>"
     },
 
     // askURL: Answers questions based on provided URL content.
@@ -100,15 +93,8 @@ Create the configuration.
       "provider": "gemini",
       "apiKey": "<GEMINI_API_KEY>"
       "model": "gemini-3-flash-preview"
-      // Optional
-      // "baseURL": "<proxy_url>"
 
       // Or use Vertex AI (Requires gcloud CLI to get authentication token)
-      // "provider": "gemini-vertex-ai",
-      // "baseURL": "https://aiplatform.googleapis.com/v1beta1/projects/<project_id>/locations/<location>",
-      // "model": "gemini-3-flash-preview"
-      // Optional:
-      // "account": "<service_account_email>"
     }
   },
 
@@ -166,6 +152,7 @@ Create the configuration.
 ```
 
 ```js
+// OpenAI-compatible provider (Ollama) example with a custom model
 {
   "platforms": [
     {
@@ -279,6 +266,9 @@ plain
 plain -m <model+variant>
 ```
 
+Interrupt the agent while it's running:
+Press **Ctrl-C** to pause auto-approve. The agent will finish the current tool call, then return to the prompt.
+
 (Optional) Set up a sandbox for your project with the `sandbox-configurator` agent.
 
 ```
@@ -292,7 +282,7 @@ After the agent finishes, run the generated setup script once to build the sandb
 ```
 
 Run in batch mode (non-interactive).
-In batch mode, config files are not loaded automatically. Only the files specified with `--config` are loaded.
+In batch mode, config files are not loaded automatically. Only the files specified with `-c` are loaded.
 
 ```sh
 plain batch \
@@ -307,9 +297,14 @@ Display the help message.
 /help
 ```
 
-Interrupt the agent while it's running:
+Show daily token costs across sessions. `plain cost` reads
+`~/.local/share/plain-agent/usage.jsonl`; use `--from` / `--to` to set the
+period. Currencies are shown separately.
 
-Press **Ctrl-C** to pause auto-approve. The agent will finish the current tool call, then return to the prompt.
+```sh
+plain cost
+plain cost --from 2026-04-01 --to 2026-04-30
+```
 
 ## Available Tools
 
@@ -327,29 +322,24 @@ The agent can use the following tools to assist with tasks:
 
 ## Configuration
 
+Files are loaded in the following order. Settings in later files override earlier ones.
+
 ```
 ~/.config/plain-agent/
-  \__ config.json        # User configuration
-  \__ config.local.json  # User local configuration (including secrets)
-  \__ prompts/           # Global/User-defined prompts
-  \__ agents/            # Global/User-defined agent roles
+  ├── (1) config.json        # User configuration
+  ├── (2) config.local.json  # User local configuration (including secrets)
+  ├── prompts/               # Global/User-defined prompts
+  └── agents/                # Global/User-defined agent roles
 
 <project-root>
-  \__ .plain-agent/
-        \__ config.json            # Project-specific configuration
-        \__ config.local.json      # Project-specific local configuration (including secrets)
-        \__ memory/                # Task-specific memory files
-        \__ prompts/               # Project-specific prompts
-        \__ agents/                # Project-specific agent roles
+  └── .plain-agent/
+        ├── (3) config.json        # Project-specific configuration
+        ├── (4) config.local.json  # Project-specific local configuration (including secrets)
+        ├── memory/                  # Task-specific memory files
+        ├── prompts/                 # Project-specific prompts
+        └── agents/                  # Project-specific agent roles
 ```
 
-The agent loads configuration files in the following order. Settings in later files will override those in earlier files.
-
-- `~/.config/plain-agent/config.json`
-- `~/.config/plain-agent/config.local.json`
-- `.plain-agent/config.json`
-- `.plain-agent/config.local.json`
-
 ### Example
 
 <details>
@@ -412,19 +402,19 @@ The agent loads configuration files in the following order. Settings in later fi
     "patterns": [
       {
         "toolName": { "$regex": "^(write_file|patch_file)$" },
-        "input": { "filePath": { "$regex": "^(\\./)?\\.plain-agent/memory/.+\\.md$" } },
+        "input": { "filePath": { "$regex": "^\\.plain-agent/memory/.+\\.md$" } },
         "action": "allow"
       },
       {
         "toolName": { "$regex": "^(write_file|patch_file)$" },
-        "input": { "filePath": { "$regex": "^(\\./)?src/" } },
+        "input": { "filePath": { "$regex": "^src/" } },
         "action": "allow"
       },
 
       // ⚠️ Arbitrary code execution can access unauthorized files and networks. Always use a sandbox.
       {
         "toolName": "exec_command",
-        "input": { "command": "npm", "args": ["run", { "$regex": "^(check|test|lint|fix)$" }] },
+        "input": { "command": "npm", "args": ["run", { "$regex": "^(lint|test)$" }] },
         "action": "allow"
       },
 
@@ -500,8 +490,8 @@ The agent loads configuration files in the following order. Settings in later fi
     }
   },
 
-  // Override default notification command
-  // "notifyCmd": "/path/to/notification-command"
+  // Override default notification command (falls back to terminal bell)
+  // "notifyCmd": { "command": "plain-notify-desktop", "args": [] }
 
   // (Optional) Voice input. See "Voice Input" below.
   // "voiceInput": {
@@ -516,6 +506,17 @@ The agent loads configuration files in the following order. Settings in later fi
 
 You can define reusable prompts in Markdown files.
 
+### Locations
+
+The agent searches for prompts in the following directories:
+
+- `~/.config/plain-agent/prompts/`
+- `.plain-agent/prompts/`
+- `.claude/commands/`
+- `.claude/skills/`
+
+The prompt ID is the relative path of the file without the `.md` extension. For example, `.plain-agent/prompts/commit.md` becomes `/prompts:commit`.
+
 ### Prompt File Format
 
 ```md
@@ -537,30 +538,8 @@ import: https://raw.githubusercontent.com/anthropics/claude-code/5cff78741f54a0d
 - Parallel execution of subagents is not supported. Delegate to subagents sequentially.
 ```
 
-```md
----
-import: https://raw.githubusercontent.com/anthropics/claude-code/db8834ba1d72e9a26fba30ac85f3bc4316bb0689/plugins/code-review/commands/code-review.md
----
-
-- Parallel execution of subagents is not supported. Delegate to subagents sequentially.
-- If CLAUDE.md is not found, refer to AGENTS.md instead for project rules and conventions.
-- If the PR branch is already checked out, review changes from local files instead of fetching from GitHub.
-- After explaining the review results to the user, ask whether to post the comments to GitHub as well.
-```
-
 Remote prompts are fetched and cached locally. The local content will be appended to the imported content.
 
-### Locations
-
-The agent searches for prompts in the following directories:
-
-- `~/.config/plain-agent/prompts/`
-- `.plain-agent/prompts/`
-- `.claude/commands/`
-- `.claude/skills/`
-
-The prompt ID is the relative path of the file without the `.md` extension. For example, `.plain-agent/prompts/commit.md` becomes `/prompts:commit`.
-
 ### Shortcuts
 
 Prompts located in a `shortcuts/` subdirectory (e.g., `.plain-agent/prompts/shortcuts/commit.md`) can be invoked directly as a top-level command (e.g., `/commit`).
@@ -569,6 +548,14 @@ Prompts located in a `shortcuts/` subdirectory (e.g., `.plain-agent/prompts/shor
 
 Subagents are specialized agents designed for specific tasks.
 
+### Locations
+
+The agent searches for subagent definitions in the following directories:
+
+- `~/.config/plain-agent/agents/`
+- `.plain-agent/agents/`
+- `.claude/agents/`
+
 ### Subagent File Format
 
 ```md
@@ -591,14 +578,6 @@ Use AGENTS.md instead of CLAUDE.md in this project.
 
 Remote subagents are fetched and cached locally. The local content will be appended to the imported content.
 
-### Locations
-
-The agent searches for subagent definitions in the following directories:
-
-- `~/.config/plain-agent/agents/`
-- `.plain-agent/agents/`
-- `.claude/agents/`
-
 ## Claude Code Plugin Support
 
 Example:
@@ -642,7 +621,7 @@ and send them like regular text.
 
 ### Providers
 
-**OpenAI Realtime** (default, recommended):
+**OpenAI Realtime**
 
 ```js
 {
@@ -655,7 +634,7 @@ and send them like regular text.
 }
 ```
 
-**Gemini Live** (preview API; model names and pricing may change):
+**Gemini Live**
 
 ```js
 {
@@ -672,8 +651,7 @@ and send them like regular text.
 
 - `toggleKey` — Rebind the toggle. Accepts `"ctrl-<char>"` where `<char>`
   is a letter (a-z) or one of `[ \ ] ^ _`. Defaults to `"ctrl-o"`.
-- `recorder` — Override recorder auto-detection. Must write raw 16-bit
-  little-endian mono PCM to stdout at 24 kHz (OpenAI) or 16 kHz (Gemini).
+- `recorder` — Override recorder auto-detection, e.g. `{ "command": "sox", "args": ["-q", "-d", "-b", "16", "-c", "1", "-r", "24000", "-e", "signed-integer", "-t", "raw", "-"] }`. Must write raw 16-bit little-endian mono PCM to stdout at 24 kHz (OpenAI) or 16 kHz (Gemini).
 
 ## Development
 
@@ -694,13 +672,9 @@ npx npm-check-updates -t minor -c 3 -u
 ## Release
 
 ```sh
-npm run check
-
-git commit -m "<message>"
-
 npm version <major|minor|patch>
-git push --follow-tags
 
+git push --follow-tags
 gh release create $(git describe --tags) --generate-notes
 
 npm publish --access public

package/config/config.predefined.json

@@ -813,7 +813,7 @@
       }
     },
     {
-      "name": "gpt-5.4",
+      "name": "gpt-5.5",
       "variant": "thinking-medium",
       "platform": {
         "name": "openai",
@@ -823,7 +823,7 @@
       "model": {
         "format": "openai-responses",
         "config": {
-          "model": "gpt-5.4",
+          "model": "gpt-5.5",
           "reasoning": { "effort": "medium", "summary": "auto" },
           "store": false,
           "include": ["reasoning.encrypted_content"]
@@ -833,14 +833,14 @@
         "currency": "USD",
         "unit": "1M",
         "costs": {
-          "input_tokens": 2.5,
-          "input_tokens_details.cached_tokens": -2.25,
-          "output_tokens": 15
+          "input_tokens": 5,
+          "input_tokens_details.cached_tokens": -4.5,
+          "output_tokens": 30
         }
       }
     },
     {
-      "name": "gpt-5.4",
+      "name": "gpt-5.5",
       "variant": "thinking-high",
       "platform": {
         "name": "openai",
@@ -850,7 +850,7 @@
       "model": {
         "format": "openai-responses",
         "config": {
-          "model": "gpt-5.4",
+          "model": "gpt-5.5",
           "reasoning": { "effort": "high", "summary": "auto" },
           "store": false,
           "include": ["reasoning.encrypted_content"]
@@ -860,14 +860,14 @@
         "currency": "USD",
         "unit": "1M",
         "costs": {
-          "input_tokens": 2.5,
-          "input_tokens_details.cached_tokens": -2.25,
-          "output_tokens": 15
+          "input_tokens": 5,
+          "input_tokens_details.cached_tokens": -4.5,
+          "output_tokens": 30
         }
       }
     },
     {
-      "name": "gpt-5.4",
+      "name": "gpt-5.5",
       "variant": "thinking-xhigh",
       "platform": {
         "name": "openai",
@@ -877,7 +877,7 @@
       "model": {
         "format": "openai-responses",
         "config": {
-          "model": "gpt-5.4",
+          "model": "gpt-5.5",
           "reasoning": { "effort": "xhigh", "summary": "auto" },
           "store": false,
           "include": ["reasoning.encrypted_content"]
@@ -887,9 +887,9 @@
         "currency": "USD",
         "unit": "1M",
         "costs": {
-          "input_tokens": 2.5,
-          "input_tokens_details.cached_tokens": -2.25,
-          "output_tokens": 15
+          "input_tokens": 5,
+          "input_tokens_details.cached_tokens": -4.5,
+          "output_tokens": 30
         }
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.7.18",
+  "version": "1.7.20",
   "description": "A lightweight CLI-based coding agent",
   "license": "MIT",
   "type": "module",
@@ -10,9 +10,7 @@
   },
   "bin": {
     "plain": "./bin/plain",
-    "plain-interrupt": "./bin/plain-interrupt",
     "plain-notify-desktop": "./bin/plain-notify-desktop",
-    "plain-notify-terminal-bell": "./bin/plain-notify-terminal-bell",
     "plain-sandbox": "./sandbox/bin/plain-sandbox"
   },
   "files": [

package/src/agentLoop.mjs

@@ -128,7 +128,9 @@ export function createAgentLoop({
 
       const { message: assistantMessage, providerTokenUsage } = modelOutput;
       stateManager.appendMessages([assistantMessage]);
-      agentEventEmitter.emit("providerTokenUsage", providerTokenUsage);
+      if (providerTokenUsage) {
+        agentEventEmitter.emit("providerTokenUsage", providerTokenUsage);
+      }
 
       // Gemini may stop with "thinking" -> continue
       const lastContent = assistantMessage.content.at(-1);

package/src/cliArgs.mjs

@@ -1,5 +1,5 @@
 /**
- * @typedef {HelpSubcommand | InteractiveSubcommand | BatchSubcommand | ListModelsSubcommand | InstallClaudeCodePluginsSubcommand} Subcommand
+ * @typedef {HelpSubcommand | InteractiveSubcommand | BatchSubcommand | ListModelsSubcommand | InstallClaudeCodePluginsSubcommand | CostSubcommand} Subcommand
  */
 
 /**
@@ -22,6 +22,10 @@
  * @typedef {{ type: 'install-claude-code-plugins' }} InstallClaudeCodePluginsSubcommand
  */
 
+/**
+ * @typedef {{ type: 'cost', from: string | null, to: string | null }} CostSubcommand
+ */
+
 /**
  * @typedef {Object} CliArgs
  * @property {Subcommand} subcommand - The subcommand to execute
@@ -106,6 +110,28 @@ export function parseCliArgs(argv) {
     };
   }
 
+  if (subcommandName === "cost") {
+    const costArgs = args.slice(1);
+    let from = null;
+    let to = null;
+    for (let i = 0; i < costArgs.length; i++) {
+      if (costArgs[i] === "--from") {
+        if (costArgs[i + 1]) {
+          from = costArgs[i + 1];
+          i++;
+        }
+      } else if (costArgs[i] === "--to") {
+        if (costArgs[i + 1]) {
+          to = costArgs[i + 1];
+          i++;
+        }
+      }
+    }
+    return {
+      subcommand: { type: "cost", from, to },
+    };
+  }
+
   return {
     subcommand: { type: "help" },
   };
@@ -119,6 +145,7 @@ export function printHelp(exitCode = 0) {
   console.log(`
 Usage: plain [options]
        plain batch [options] <task>
+       plain cost [--from YYYY-MM-DD] [--to YYYY-MM-DD]
        plain list-models
        plain install-claude-code-plugins
 
@@ -131,6 +158,9 @@ Subcommands:
   batch <task>                 Run in batch mode with the given task instruction.
                                Config files are NOT auto-loaded in batch mode;
                                use -c to specify config files explicitly.
+  cost                         Show aggregated token cost per day for a period.
+                               Defaults to the first day of the current month
+                               through today.
   list-models                  List available models
   install-claude-code-plugins  Install Claude Code plugins
 

package/src/cliBatch.mjs

@@ -3,6 +3,7 @@
  */
 
 import { formatCostForBatch } from "./cliFormatter.mjs";
+import { appendUsageRecord, buildUsageRecord } from "./usageStore.mjs";
 
 /**
  * @typedef {object} BatchSessionOptions
@@ -46,6 +47,27 @@ export async function startBatchSession({
         timestamp: new Date().toISOString(),
         cost: formatCostForBatch(costSummary),
       });
+
+      try {
+        const record = buildUsageRecord({
+          sessionId,
+          mode: "batch",
+          modelName,
+          workingDir: process.cwd(),
+          costSummary,
+        });
+        if (record) {
+          await appendUsageRecord(record);
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        outputEvent({
+          type: "error",
+          error: { message: `failed to record usage: ${message}` },
+          timestamp: new Date().toISOString(),
+        });
+      }
+
       await onStop();
       resolve();
     });