claude-teammate 0.1.20 → 0.1.22

package/README.md

@@ -91,14 +91,18 @@ memory/
 
 ## Quickstart
 
-**Requirements:** Node.js 20+, [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated, a Jira API token, a GitHub PAT with repo + PR permissions.
+**Requirements:**
+- Node.js 20+
+- [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+- A Jira API token
+- A GitHub PAT with `repo` + PR permissions
 
 ```bash
 npm install -g claude-teammate
 tm8 start
 ```
 
-`start` creates `.env` on the first run, runs a 5 second Claude CLI preflight check that expects a plain `OK`, then launches a background worker for the current project. If `.env` already exists with the required values, setup is skipped and your credentials are not prompted for again.
+`start` creates `.env` on the first run, then launches a background worker for the current project. If `.env` already exists with the required values, setup is skipped and your credentials are not prompted for again.
 
 To upgrade to latest version
 
@@ -163,6 +167,19 @@ It reads the actual repository before writing anything - structure, conventions,
 
 <br/>
 
+## Roadmap
+
+- GitLab support
+- Bitbucket support
+- Ensure no conflicts for multiple concurrent claude-teammate agents
+- Slack and Teams notifications when PRs are opened or merged
+- Automatic PR description generation from commit history and issue context
+- Branch-naming convention enforcement per epic or project config
+- Stale-issue nudges when tickets sit unactioned past a configurable threshold
+- Test-coverage gating before issue closure
+
+<br/>
+
 ## Contributing
 
 Contributions are welcome. Open an issue to discuss before submitting large changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-teammate",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "CLI bootstrapper for Claude Teammate.",
   "license": "MIT",
   "type": "module",

package/src/cli.js

@@ -5,22 +5,28 @@ import { runStatusCommand } from "./commands/status.js";
 import { runStopCommand } from "./commands/stop.js";
 import { runWorkerCommand } from "./commands/worker.js";
 
+const LOCAL_FLAG = "--local";
+const COMMANDS_WITH_LOCAL_FLAG = new Set(["start", "stop", "status"]);
+
 const HELP_TEXT = `claude-teammate
 
 Usage:
-  claude-teammate start
-  claude-teammate stop
-  claude-teammate status
+  claude-teammate start [${LOCAL_FLAG}]
+  claude-teammate stop [${LOCAL_FLAG}]
+  claude-teammate status [${LOCAL_FLAG}]
   claude-teammate --help
 
 Commands:
-  start     Start Claude Teammate in the background for this project
-  stop      Stop the background worker for this project
+  start     Start Claude Teammate in the background (default: global mode using ~/.tm8)
+  stop      Stop the background worker
   status    Show worker status, logs, and last Jira poll state
+
+Flags:
+  ${LOCAL_FLAG}   Use the current project directory instead of the global ~/.tm8 directory
 `;
 
 export async function runCli(args) {
-  const [command] = args;
+  const [command, ...remainingArgs] = args;
   const projectRoot = process.cwd();
   const entrypointPath = process.argv[1];
 
@@ -29,23 +35,30 @@ export async function runCli(args) {
     return;
   }
 
+  const invalidFlag = findInvalidFlag(command, remainingArgs);
+  if (invalidFlag) {
+    process.stderr.write(`Unknown flag for ${command}: ${invalidFlag}\n\n${HELP_TEXT}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
   if (command === "start") {
-    await runStartCommand({ projectRoot, entrypointPath });
+    await runStartCommand({ projectRoot, entrypointPath, args: remainingArgs });
     return;
   }
 
   if (command === "stop") {
-    await runStopCommand({ projectRoot });
+    await runStopCommand({ projectRoot, args: remainingArgs });
     return;
   }
 
   if (command === "status") {
-    await runStatusCommand({ projectRoot });
+    await runStatusCommand({ projectRoot, args: remainingArgs });
     return;
   }
 
   if (command === "run-worker") {
-    const workerProjectRoot = args[1];
+    const workerProjectRoot = remainingArgs[0];
     if (!workerProjectRoot) {
       throw new Error("Missing project root for run-worker.");
     }
@@ -57,3 +70,17 @@ export async function runCli(args) {
   process.stderr.write(`Unknown command: ${command}\n\n${HELP_TEXT}\n`);
   process.exitCode = 1;
 }
+
+export function findInvalidFlag(command, args) {
+  if (!COMMANDS_WITH_LOCAL_FLAG.has(command)) {
+    return null;
+  }
+
+  for (const arg of args) {
+    if (arg.startsWith("-") && arg !== LOCAL_FLAG) {
+      return arg;
+    }
+  }
+
+  return null;
+}

package/src/commands/start.js

@@ -6,17 +6,21 @@ import process from "node:process";
 import { ensurePlaywrightMcpAvailable, verifyClaudeCli } from "../claude.js";
 import {
   REQUIRED_FIELDS,
+  ensureGlobalConfigDir,
   getMissingFields,
   loadProjectEnv,
   persistEnvFile
 } from "../config.js";
 import { ensureRuntimeDir, isProcessRunning, readPid, removePid } from "../runtime.js";
 
-export async function runStartCommand({ projectRoot, entrypointPath }) {
-  const { values } = await loadProjectEnv(projectRoot);
+export async function runStartCommand({ projectRoot, entrypointPath, args = [] }) {
+  const isLocal = args.includes("--local");
+  const configRoot = isLocal ? projectRoot : await ensureGlobalConfigDir();
+
+  const { values } = await loadProjectEnv(configRoot);
 
   if (Object.keys(values).length === 0) {
-    await runSetupWizard(projectRoot);
+    await runSetupWizard(configRoot);
   } else {
     const missingFields = getMissingFields(values);
 
@@ -25,7 +29,7 @@ export async function runStartCommand({ projectRoot, entrypointPath }) {
     }
   }
 
-  const runtimePaths = await ensureRuntimeDir(projectRoot);
+  const runtimePaths = await ensureRuntimeDir(configRoot);
   const existingPid = await readPid(runtimePaths.pidFile);
 
   if (existingPid && isProcessRunning(existingPid)) {
@@ -40,12 +44,12 @@ export async function runStartCommand({ projectRoot, entrypointPath }) {
 
   process.stdout.write("Checking Claude CLI...\n");
   await verifyClaudeCli({
-    cwd: projectRoot,
+    cwd: configRoot,
     timeoutMs: 15_000
   });
   process.stdout.write("Checking Playwright MCP...\n");
   const playwrightMcp = await ensurePlaywrightMcpAvailable({
-    cwd: projectRoot,
+    cwd: configRoot,
     scope: "user",
     timeoutMs: 15_000,
     installTimeoutMs: 60_000
@@ -57,8 +61,8 @@ export async function runStartCommand({ projectRoot, entrypointPath }) {
   }
 
   const logFd = openSync(runtimePaths.logFile, "a");
-  const child = spawn(process.execPath, [entrypointPath, "run-worker", projectRoot], {
-    cwd: projectRoot,
+  const child = spawn(process.execPath, [entrypointPath, "run-worker", configRoot], {
+    cwd: configRoot,
     detached: true,
     stdio: ["ignore", logFd, logFd]
   });
@@ -70,7 +74,7 @@ export async function runStartCommand({ projectRoot, entrypointPath }) {
   process.stdout.write(`Logs: ${runtimePaths.logFile}\n`);
 }
 
-async function runSetupWizard(projectRoot) {
+async function runSetupWizard(configRoot) {
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
     throw new Error("The start wizard requires an interactive terminal.");
   }
@@ -88,7 +92,7 @@ async function runSetupWizard(projectRoot) {
       values[field.key] = await promptForValue(rl, field);
     }
 
-    await persistEnvFile(projectRoot, values);
+    await persistEnvFile(configRoot, values);
     process.stdout.write("\nSaved configuration to .env.\n");
   } finally {
     rl.close();

package/src/commands/status.js

@@ -1,9 +1,12 @@
 import process from "node:process";
 
+import { ensureGlobalConfigDir } from "../config.js";
 import { ensureRuntimeDir, isProcessRunning, readPid, readState, removePid } from "../runtime.js";
 
-export async function runStatusCommand({ projectRoot }) {
-  const runtimePaths = await ensureRuntimeDir(projectRoot);
+export async function runStatusCommand({ projectRoot, args = [] }) {
+  const isLocal = args.includes("--local");
+  const configRoot = isLocal ? projectRoot : await ensureGlobalConfigDir();
+  const runtimePaths = await ensureRuntimeDir(configRoot);
   const pid = await readPid(runtimePaths.pidFile);
   const state = await readState(runtimePaths.stateFile);
 

package/src/commands/stop.js

@@ -1,9 +1,12 @@
 import process from "node:process";
 
+import { ensureGlobalConfigDir } from "../config.js";
 import { ensureRuntimeDir, isProcessRunning, readPid, removePid } from "../runtime.js";
 
-export async function runStopCommand({ projectRoot }) {
-  const runtimePaths = await ensureRuntimeDir(projectRoot);
+export async function runStopCommand({ projectRoot, args = [] }) {
+  const isLocal = args.includes("--local");
+  const configRoot = isLocal ? projectRoot : await ensureGlobalConfigDir();
+  const runtimePaths = await ensureRuntimeDir(configRoot);
   const pid = await readPid(runtimePaths.pidFile);
 
   if (!pid) {

package/src/config.js

@@ -1,8 +1,20 @@
-import { access, readFile, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 export const ENV_FILE_NAME = ".env";
+
+export function getGlobalConfigDir() {
+  return path.join(os.homedir(), ".tm8");
+}
+
+export async function ensureGlobalConfigDir() {
+  const dir = getGlobalConfigDir();
+  await mkdir(dir, { recursive: true });
+  return dir;
+}
+
 export const REQUIRED_FIELDS = [
   {
     key: "JIRA_BASE_URL",