agenter-app 0.0.0-stage → 1.0.0

package/Agenter.vbs

@@ -0,0 +1,9 @@
+' Double-click (or use the shortcut) to open Agenter without a console window.
+' "Agenter.vbs server" only starts the background server (used at Windows login).
+Set fso = CreateObject("Scripting.FileSystemObject")
+dir = fso.GetParentFolderName(WScript.ScriptFullName)
+cmd = "node """ & dir & "\open.js"""
+If WScript.Arguments.Count > 0 Then
+  If WScript.Arguments(0) = "server" Then cmd = "node """ & dir & "\server.js"" --no-open"
+End If
+CreateObject("WScript.Shell").Run cmd, 0, False

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmad Pandaog Aquino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,169 @@
-# Temporary Holding Version
+# Agenter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One dashboard for every Claude Code and Codex session on this machine, across all your VS Code windows.
+
+- See every session live: what it's doing, which command it's running, and the full conversation.
+- Approve or deny permission prompts (PowerShell/Bash commands, file edits, web fetches…) from one place.
+- Answer Claude's multiple-choice questions.
+- **Message any session at any time**, drive it from VS Code or from Agenter, or start a new one.
+- Get a sound and a desktop notification whenever a session needs you.
+
+No dependencies, just Node 18+. Built for Windows.
+
+## Install
+
+```powershell
+npm install -g agenter-app
+agenter install   # adds hooks to ~/.claude/settings.json (a backup is made) + Desktop/Start Menu shortcuts
+```
+
+Then **reload each VS Code window** (or start new Claude sessions). Hooks are read when a session starts.
+
+Install it globally (`-g`), not with `npx`: the hooks point at the installed files, so they need to stay put.
+If you move Node (a new Node version manager install, say), run `agenter install` again; it replaces the old hooks.
+
+From a clone instead: `npm run install-hooks` and `npm run shortcuts`, then `npm run open`.
+
+## Running it
+
+You mostly don't have to: **the server starts itself** the first time any Claude session fires a hook,
+and keeps running in the background. Just open the window when you want it:
+
+| Way | What it does |
+|---|---|
+| **Agenter shortcut** (Desktop / Start Menu / taskbar) | Opens the dashboard in its own app window and starts the server if needed. No console. |
+| `agenter` | Same thing, from a terminal. |
+| `agenter start` | Runs the server in the foreground with logs (handy for debugging). |
+| `agenter shortcuts --startup` | Also starts the server silently when you log in to Windows. |
+
+Set `AGENTER_AUTOSTART=0` to stop hooks from starting the server.
+Dashboard settings are kept in `~/.agenter/settings.json`.
+
+To remove everything: `agenter uninstall`, then `npm uninstall -g agenter-app`.
+
+## Sessions you see
+
+- **Live**: sessions talking to Agenter right now (working, waiting for you, or idle).
+- **Earlier today**: every session you used today, found from Claude's transcripts in `~/.claude/projects`,
+  including ones started before Agenter was running and ones you've closed. You can read their full
+  conversation and click **Open in VS Code** to jump to the project. When you continue one in VS Code,
+  it moves to Live.
+
+**Clear earlier** hides those until they become active again.
+
+## Steer from Agenter
+
+Every live session has a message box at the bottom, so you never have to switch to VS Code to tell Claude something.
+
+| Claude is… | Your message |
+|---|---|
+| Waiting for your reply (finished turn) | Goes in right away and Claude continues. |
+| Working | Is queued and reaches Claude after its current step (the next tool call finishes). If the turn ends first, Claude continues with it. |
+| Idle, driven from VS Code | Is queued and goes along with your next prompt from VS Code. Claude Code can't be woken up from outside. |
+| Idle, driven from Agenter | Starts a new turn right away, run by Agenter. |
+
+Queued messages show above the box, with **Cancel**.
+
+### Drive from VS Code or Agenter
+
+Each session has a **Drive from** switch in its header.
+
+- **VS Code** (default): Claude runs in the VS Code panel. Agenter answers inside its turns, so while you
+  reply from Agenter the VS Code panel shows its spinner, and an idle session waits for VS Code.
+- **Agenter**: Agenter runs the turns itself with the Claude Code that ships with the VS Code extension
+  (`claude -p --resume <session>`), in the same session. Nothing ever waits on VS Code, idle and closed
+  sessions can be continued, permission prompts and questions come to Agenter, and **Stop** ends a running turn.
+  The VS Code panel doesn't show these turns until you reopen the session there (Claude panel → session
+  history), and don't type in VS Code's panel for that session at the same time.
+
+If Claude Code isn't found automatically, set `AGENTER_CLAUDE` to the path of `claude.exe`.
+
+### Start a session in Agenter
+
+**New session** (sidebar) starts a Claude session without VS Code: pick the project folder (folders you've
+used are suggested), type the first message, and it runs in Agenter, driven from Agenter. You can still open
+it in VS Code later from the Claude panel's session history.
+
+## Codex
+
+Agenter also shows your [Codex](https://developers.openai.com/codex) sessions (VS Code extension, desktop app
+and CLI), read from Codex's own session logs in `~/.codex/sessions`. Nothing is sent anywhere and Codex's
+settings aren't changed.
+
+- **Sessions**: today's Codex sessions appear in the list with a **Codex** tag: the conversation, the
+  commands it ran, and whether it's working right now. Codex's helper threads (like its auto-review) are left out.
+- **Steering**: each Codex session has a **Drive from** switch and a message box.
+  - **Codex app** (default): your message is queued in Codex (`codex queue`) and runs as the session's next
+    turn when it's open in Codex (VS Code extension or desktop app).
+  - **Agenter**: Agenter runs the turns itself (`codex exec resume`), sandboxed to the project folder
+    (`workspace-write`, no network), since nobody is there to approve anything more. A message sent while a
+    turn is running goes next. **Stop** ends a running turn.
+- **New session** can start a Codex session too (pick **Codex** in the dialog). It runs in Agenter and also
+  shows up in the Codex app.
+
+Agenter uses the Codex that ships with the Codex VS Code extension, or `codex` on your PATH. Set
+`AGENTER_CODEX_BIN` to point at another `codex.exe`.
+- **Plan usage**: the sidebar shows your Codex **5-hour** and **weekly** limits with reset times, with the
+  same alerts at 80% and 95%. Codex records these with each turn, so they're as of your last Codex turn
+  (a window that has reset since shows 0%).
+
+Set `CODEX_HOME` if Codex keeps its data somewhere else, or `AGENTER_CODEX=0` to turn this off.
+
+## Preview the app side by side
+
+Click **Preview** in a session's header to show the app you're building next to the conversation, so you
+can steer Claude and watch the result in one window.
+
+- Agenter finds web servers started from that project's folder (`npm run dev`, Vite, Next, etc.) and shows
+  the first page it finds. Other servers it finds appear as chips you can switch between.
+  Start the dev server later and it shows up within a few seconds.
+- Or type any address in the bar (`5173` is short for `http://localhost:5173`). It's remembered per project;
+  clear it to go back to the detected app.
+- Drag the divider to resize (double-click to reset). **Open** (↗) opens the app in your normal browser.
+- Some apps refuse to be shown inside another page. If the preview stays blank, use **Open**.
+- Finding apps works on Windows. Elsewhere, type the address.
+
+## How it works
+
+Claude Code runs [hooks](https://docs.claude.com/en/docs/claude-code/hooks) on events such as
+"about to use a tool", "needs permission" and "finished its turn". Each hook runs `hook.js`, which
+forwards the event to the local server (`server.js`) and prints the server's answer back to Claude.
+
+| Event | What Agenter does |
+|---|---|
+| `PermissionRequest` | Holds the prompt until you click **Allow / Always allow / Deny / Answer in VS Code**. A deny reason is passed to Claude, so you can say "no, do X instead". |
+| `PreToolUse` (AskUserQuestion) | Shows the question with its options; your answers go back to Claude. |
+| `Stop` | If **Hold for reply** is on, the session waits for your next instruction. **Send** continues it; **Release to VS Code** lets it stop normally. |
+| Everything else | Activity feed and status only (never blocks). |
+
+### Safety valves
+
+- **Server not running?** Hooks exit instantly and Claude behaves as if Agenter didn't exist.
+- **Working in VS Code?** Sessions are only held while the dashboard window has focus. Switch to VS Code
+  and nothing new gets held, and anything already waiting goes back to VS Code after 5 seconds.
+- **Dashboard closed?** Same, after 15 seconds.
+- **Interrupt in VS Code** while something is waiting? The dashboard item disappears.
+- The server only listens on `127.0.0.1` and rejects requests from other websites.
+
+## Plan usage
+
+(Codex usage is covered under [Codex](#codex).) The sidebar shows how much of your Claude plan you've used: the **5-hour session** limit and the **weekly**
+limit, each with when it resets. You get an alert at 80% and 95%, and a banner in the inbox when the session
+limit is nearly used up. It refreshes every 2 minutes (or click ↻).
+
+It asks Anthropic using the login Claude Code already saved on this machine (`~/.claude/.credentials.json`),
+the same way Claude Code's `/usage` does. The token only goes to `api.anthropic.com`, and Agenter never
+refreshes it itself. This endpoint isn't officially documented, so it could change. Set `AGENTER_USAGE=0` to turn it off.
+
+## Tips and limits
+
+- **Hold for reply** is the global default (sidebar) and can be turned off per session. While a session is
+  held, its VS Code panel shows the "Clauding…" spinner. That's expected. To get it back in VS Code:
+  click **Release to VS Code** in the dashboard, press **Esc** in VS Code, or just wait. Anything waiting is
+  handed back automatically after **Hand back to VS Code after** (3 min by default, with a countdown on the card).
+- An idle session that has been *released* can't be woken up from the dashboard, because Claude Code only
+  hands control to hooks at events. A message you send then waits for your next prompt from VS Code.
+- Answering `AskUserQuestion` from the dashboard depends on your Claude Code version accepting
+  hook-supplied answers. If it doesn't, use **Answer in VS Code**.
+- Port: set `AGENTER_PORT` for both the server and your environment if 4317 is taken.
+- `npm start -- --no-open` skips opening the browser.

package/cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// The `agenter` command (npm i -g agenter-app). Each subcommand runs one of the existing scripts.
+'use strict';
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { version } = require('./package.json');
+
+const [cmd = 'open', ...rest] = process.argv.slice(2);
+const isWindows = process.platform === 'win32';
+
+const node = (script, args = []) =>
+  spawnSync(process.execPath, [path.join(__dirname, script), ...args], { stdio: 'inherit' }).status ?? 1;
+
+const shortcuts = (args = []) => {
+  if (!isWindows) {
+    console.log('Shortcuts are Windows only. Skipped.');
+    return 0;
+  }
+  const ps1 = path.join(__dirname, 'scripts', 'install-shortcuts.ps1');
+  return spawnSync('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', ps1, ...args], { stdio: 'inherit' }).status ?? 1;
+};
+
+const help = `Agenter ${version}: one inbox for every Claude Code and Codex session.
+
+Usage: agenter [command]
+
+  (none), open     Open the dashboard (starts the server if needed)
+  install          Add Agenter's hooks to ~/.claude/settings.json (backed up first)
+                   and, on Windows, Desktop and Start Menu shortcuts
+  uninstall        Remove the hooks and shortcuts
+  start            Run the server in the foreground with logs
+  shortcuts        (Re)create the Windows shortcuts; --startup also starts the server at login
+  version          Print the version
+
+After installing, reload your VS Code windows so Claude sessions pick up the hooks.`;
+
+let status = 0;
+switch (cmd) {
+  case 'open':
+    status = node('open.js', rest);
+    break;
+  case 'install':
+    status = node('install.js', rest);
+    if (status === 0) status = shortcuts();
+    break;
+  case 'uninstall':
+    status = node('install.js', ['--uninstall']);
+    shortcuts(['-Remove']);
+    break;
+  case 'start':
+    status = node('server.js', rest);
+    break;
+  case 'shortcuts':
+    status = shortcuts(rest.includes('--startup') ? ['-Startup'] : []);
+    break;
+  case 'version':
+  case '--version':
+  case '-v':
+    console.log(version);
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+    console.log(help);
+    break;
+  default:
+    console.error(`Unknown command: ${cmd}\n`);
+    console.log(help);
+    status = 1;
+}
+process.exit(status);

package/hook.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Claude Code hook bridge. Claude Code runs this for every hook event and pipes the
+// event JSON on stdin. We forward it to the Agenter server and print whatever it
+// answers. If the server isn't running we start it in the background (unless
+// AGENTER_AUTOSTART=0) and exit silently so Claude behaves normally this time.
+'use strict';
+const http = require('node:http');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const PORT = Number(process.env.AGENTER_PORT) || 4317;
+
+function startServer() {
+  if (process.env.AGENTER_AUTOSTART === '0') return;
+  try {
+    spawn(process.execPath, [path.join(__dirname, 'server.js'), '--no-open'], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+  } catch {}
+}
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => (input += chunk));
+process.stdin.on('end', () => {
+  const req = http.request(
+    {
+      host: '127.0.0.1',
+      port: PORT,
+      path: '/hook',
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(input) },
+    },
+    (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => (body += chunk));
+      res.on('end', () => {
+        const out = body.trim();
+        if (res.statusCode === 200 && out && out !== '{}') process.stdout.write(out);
+        process.exit(0);
+      });
+    }
+  );
+  // Server down or unreachable: fall back to Claude's normal behaviour.
+  req.on('error', (err) => {
+    if (err.code === 'ECONNREFUSED') startServer();
+    process.exit(0);
+  });
+  req.end(input);
+});

package/install.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Adds (or with --uninstall removes) the Agenter hooks in ~/.claude/settings.json.
+// Existing settings and other hooks are left untouched; a backup is written first.
+'use strict';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
+const HOOK_SCRIPT = path.join(__dirname, 'hook.js').replace(/\\/g, '/');
+const COMMAND = `node "${HOOK_SCRIPT}"`;
+
+// timeout is in seconds. Events that can wait for you get an hour.
+const EVENTS = {
+  SessionStart: { timeout: 10 },
+  SessionEnd: { timeout: 10 },
+  UserPromptSubmit: { timeout: 10 },
+  PreToolUse: { matcher: '*', timeout: 3600 },
+  PostToolUse: { matcher: '*', timeout: 10 },
+  PermissionRequest: { matcher: '*', timeout: 3600 },
+  Notification: { timeout: 10 },
+  Stop: { timeout: 3600 },
+  SubagentStop: { timeout: 10 },
+};
+
+const uninstall = process.argv.includes('--uninstall');
+
+let settings = {};
+if (fs.existsSync(SETTINGS)) {
+  const raw = fs.readFileSync(SETTINGS, 'utf8');
+  try {
+    settings = JSON.parse(raw);
+  } catch (err) {
+    console.error(`Could not parse ${SETTINGS}: ${err.message}\nFix the file and run again.`);
+    process.exit(1);
+  }
+  const backup = `${SETTINGS}.agenter-backup-${Date.now()}`;
+  fs.writeFileSync(backup, raw);
+  console.log(`Backed up settings to ${backup}`);
+} else {
+  fs.mkdirSync(path.dirname(SETTINGS), { recursive: true });
+}
+
+// Also matches hooks left behind by an older copy of Agenter at another path.
+const isOurs = (h) =>
+  h && typeof h.command === 'string' && (h.command.includes(HOOK_SCRIPT) || /agenter[^"]*\/hook\.js"$/i.test(h.command));
+
+settings.hooks = settings.hooks || {};
+for (const [event, groups] of Object.entries(settings.hooks)) {
+  if (!Array.isArray(groups)) continue;
+  settings.hooks[event] = groups
+    .map((g) => ({ ...g, hooks: (g.hooks || []).filter((h) => !isOurs(h)) }))
+    .filter((g) => g.hooks.length > 0);
+  if (settings.hooks[event].length === 0) delete settings.hooks[event];
+}
+
+if (!uninstall) {
+  for (const [event, { matcher, timeout }] of Object.entries(EVENTS)) {
+    const group = { hooks: [{ type: 'command', command: COMMAND, timeout }] };
+    if (matcher) group.matcher = matcher;
+    (settings.hooks[event] = settings.hooks[event] || []).push(group);
+  }
+}
+if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+fs.writeFileSync(SETTINGS, JSON.stringify(settings, null, 2) + '\n');
+console.log(
+  uninstall
+    ? 'Agenter hooks removed.'
+    : `Agenter hooks installed for: ${Object.keys(EVENTS).join(', ')}\n` +
+        'Restart your Claude sessions (or reload the VS Code windows) so they pick up the hooks.\n' +
+        'Then run: agenter'
+);

package/lib/open-dashboard.js

@@ -0,0 +1,26 @@
+'use strict';
+// Opens the dashboard in its own app window (Edge/Chrome --app) when possible,
+// otherwise in the default browser.
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn, exec } = require('node:child_process');
+
+function findAppBrowser() {
+  if (process.platform !== 'win32') return null;
+  const roots = [process.env['ProgramFiles(x86)'], process.env.ProgramFiles, process.env.LOCALAPPDATA].filter(Boolean);
+  const rels = [path.join('Microsoft', 'Edge', 'Application', 'msedge.exe'), path.join('Google', 'Chrome', 'Application', 'chrome.exe')];
+  for (const rel of rels) for (const root of roots) if (fs.existsSync(path.join(root, rel))) return path.join(root, rel);
+  return null;
+}
+
+module.exports = function openDashboard(url) {
+  const browser = findAppBrowser();
+  if (browser) {
+    const child = spawn(browser, [`--app=${url}`, '--window-size=1280,860'], { detached: true, stdio: 'ignore' });
+    child.on('error', () => {});
+    child.unref();
+    return;
+  }
+  const cmd = process.platform === 'win32' ? `start "" "${url}"` : process.platform === 'darwin' ? `open ${url}` : `xdg-open ${url}`;
+  exec(cmd, () => {});
+};

package/open.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// One-click launcher: starts the server in the background if it isn't running,
+// then opens the dashboard window. Safe to run any number of times.
+'use strict';
+const http = require('node:http');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const openDashboard = require('./lib/open-dashboard');
+
+const PORT = Number(process.env.AGENTER_PORT) || 4317;
+const URL = `http://localhost:${PORT}`;
+
+const isUp = () =>
+  new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port: PORT, path: '/', headers: { host: `127.0.0.1:${PORT}` } }, (res) => {
+      res.resume();
+      resolve(res.statusCode === 200);
+    });
+    req.on('error', () => resolve(false));
+    req.setTimeout(1000, () => req.destroy());
+  });
+
+(async () => {
+  if (!(await isUp())) {
+    spawn(process.execPath, [path.join(__dirname, 'server.js'), '--no-open'], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+    for (let i = 0; i < 40 && !(await isUp()); i++) await new Promise((r) => setTimeout(r, 150));
+  }
+  openDashboard(URL);
+})();

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "agenter-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "One local dashboard to watch, approve and steer every Claude Code and Codex session on your machine.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "codex",
+    "ai-agents",
+    "dashboard",
+    "hooks",
+    "vscode"
+  ],
+  "author": "Ahmad Pandaog Aquino (https://ahmad-new-portfolio.vercel.app/)",
+  "license": "MIT",
+  "homepage": "https://github.com/zxcoding123/agenter_app#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zxcoding123/agenter_app.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zxcoding123/agenter_app/issues"
+  },
+  "bin": {
+    "agenter": "cli.js"
+  },
+  "files": [
+    "cli.js",
+    "hook.js",
+    "install.js",
+    "open.js",
+    "server.js",
+    "Agenter.vbs",
+    "lib/",
+    "public/",
+    "scripts/"
+  ],
+  "scripts": {
+    "start": "node server.js",
+    "open": "node open.js",
+    "shortcuts": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install-shortcuts.ps1",
+    "shortcuts:startup": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install-shortcuts.ps1 -Startup",
+    "install-hooks": "node install.js",
+    "uninstall-hooks": "node install.js --uninstall"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}