localant 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chatgpt-local-app contributors
+
+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

@@ -0,0 +1,290 @@
+# LocalAnt
+
+> **Use ChatGPT as the brain. Use your local computer as the hands.**
+
+`LocalAnt` lets you use ChatGPT as the brain and your local computer as the hands.
+
+It exposes safe, permissioned local skills to ChatGPT through MCP:
+run approved commands, inspect projects, manage files, call coding agents like
+Claude Code or Codex, control browser/ADB, publish articles, and create your own
+local skills — all behind a default-deny security model with local approval and
+full audit logging.
+
+```text
+ChatGPT
+  ↓ Apps SDK / MCP Connector (Streamable HTTP /mcp)
+LocalAnt  ── Gateway · Risk engine · Approval queue · Audit log · Dashboard
+  ↓ Local PC
+  ├─ Shell (allowlisted) · Filesystem (allowlisted) · Git
+  ├─ Claude Code / Codex (plan → approve → execute → validate → diff)
+  ├─ Browser (Playwright, isolated profile) · Android (ADB)
+  ├─ Articles (Zenn / Qiita / note) · Custom Skills
+  └─ Adapters: OpenClaw · Desktop Commander · any MCP server
+```
+
+---
+
+## What is LocalAnt?
+
+A **local-first MCP Gateway** for ChatGPT. ChatGPT is the conversational UI and
+decision-maker; your PC is the execution environment. The gateway publishes a
+catalog of **140+ permissioned tools** over the Model Context Protocol, which
+ChatGPT's Developer-Mode connectors can call.
+
+The design is inspired by OpenClaw (local gateway + skills + registry),
+Desktop Commander (local PC control + audit + hardening), supergateway
+(stdio→Streamable-HTTP `/mcp`), and mcp-proxy (bundling MCP servers) — but the
+brain is **ChatGPT**, and every capability is wrapped in permissions, approval,
+and audit.
+
+## Why ChatGPT as brain, local PC as hands?
+
+- ChatGPT is great at reasoning, planning, and conversation.
+- Your PC is where your code, files, devices, and tools actually live.
+- Handing ChatGPT a raw shell is dangerous. Instead, this gateway gives it a
+  **curated, permissioned surface** with local approval for anything risky.
+
+## Features
+
+- 🔒 **Default-deny security**: allowlisted dirs/commands, blocklist, path &
+  symlink traversal prevention, secret vault + redaction.
+- ✅ **Local approval queue**: risk-2+ tools require explicit approval in the
+  dashboard or CLI — ChatGPT's confirmation is never trusted alone.
+- 🧾 **Full audit log**: every tool call recorded (with secrets redacted).
+- 🧩 **Skill system**: create, validate, enable, run, install-from-git,
+  publish, and **generate skills from ChatGPT** (always saved disabled).
+- 🤖 **Coding agents**: drive Claude Code / Codex (plan → approve → execute →
+  validate → diff) on registered projects.
+- 🖥️ **Local dashboard**: status, approvals, audit, skills, projects, secrets, agents.
+- 🌐 **3-minute setup** with Cloudflare Tunnel / ngrok and clipboard copy.
+- 🔌 **Adapters** for OpenClaw, Desktop Commander, and arbitrary MCP servers.
+
+## 3-minute setup
+
+```bash
+npx -y localant setup
+```
+
+or:
+
+```bash
+npm install -g localant
+localant setup
+```
+
+`setup` checks your environment, initializes config, generates an auth token,
+enables built-in skills, starts the gateway + dashboard, opens a public tunnel,
+copies the MCP URL to your clipboard, and prints the ChatGPT connection steps.
+
+```text
+✅ LocalAnt is running
+
+  Local Gateway:  http://127.0.0.1:8787
+  Dashboard:      http://127.0.0.1:8788
+  MCP Endpoint:   https://xxxxx.trycloudflare.com/mcp?key=********
+
+Connect ChatGPT:
+  1. Open ChatGPT → Settings → Apps & Connectors
+  2. Advanced settings → Developer Mode ON
+  3. Connectors → Create
+  4. Paste the MCP URL above
+  5. Name it: LocalAnt
+```
+
+> **From source** (this repo): `pnpm install && pnpm build && node packages/cli/dist/bin.js setup`
+
+## ChatGPT setup
+
+1. ChatGPT → **Settings → Apps & Connectors**
+2. **Advanced settings → Developer Mode ON**
+3. **Connectors → Create**
+4. Paste the **MCP URL** (`https://…/mcp?key=<token>`)
+5. Name it **LocalAnt**
+6. Ask ChatGPT: *"Run health check on my local app"*
+
+The token is embedded in the URL so the connector authenticates even where
+custom headers aren't available. You can also send `Authorization: Bearer <token>`.
+See [docs/chatgpt-setup.md](docs/chatgpt-setup.md).
+
+## Security model
+
+| Risk | Meaning | Approval |
+|------|---------|----------|
+| 0 | read-only | none |
+| 1 | safe write draft | config (default none) |
+| 2 | file modification | **required** |
+| 3 | shell / agent / network write | **required** |
+| 4 | destructive / publish / deploy | **double approval** |
+
+- No raw shell by default — only `shell_run_allowed_command` against an allowlist.
+- Filesystem access limited to **allowed directories**; sensitive paths
+  (`~/.ssh`, `~/.aws`, `/etc`, …) are always blocked; symlink escapes are caught.
+- Secrets live in an encrypted local vault and are **redacted** from tool
+  output and the audit log.
+- Generated/installed skills are **disabled by default** until you review them.
+
+Full details: [SECURITY.md](SECURITY.md).
+
+## Dashboard
+
+A local-only dashboard (`http://127.0.0.1:8788`) shows status, the MCP endpoint
+(with copy button), pending approvals, the audit log, skills (enable/disable),
+projects, secret names, and coding agents.
+
+## Skills
+
+Skills are the unit of extension. Layout:
+
+```text
+skills/<name>/
+  skill.json     # manifest: permissions + risk + tool schemas
+  README.md  LICENSE  CHANGELOG.md
+  src/index.ts   # defineSkill({...})
+  tests/index.test.ts
+  examples/
+```
+
+Manage them with `skill_list/info/enable/disable/run/validate/...` tools or the
+CLI (`localant skills ...`). See [docs/skills.md](docs/skills.md).
+
+### How to create a skill
+
+```ts
+import { defineSkill, z } from "@LocalAnt/skill-sdk";
+
+export default defineSkill({
+  name: "hello-world",
+  tools: {
+    hello: {
+      description: "Say hello",
+      riskLevel: 0,
+      inputSchema: z.object({ name: z.string() }),
+      handler: async ({ name }) => ({ content: `Hello ${name}` }),
+    },
+  },
+});
+```
+
+### How to generate a skill from ChatGPT
+
+> "Create a skill named `qiita-private-post` that posts private Qiita articles
+> using a QIITA_TOKEN secret."
+
+ChatGPT calls `skill_generate_from_prompt`. The gateway scaffolds the manifest,
+README, source and tests, **infers permissions**, sets it **disabled**, and runs
+validation. You review permissions in the dashboard, then `skill_enable` (which
+requires approval). See [docs/skills.md](docs/skills.md).
+
+## How to connect Claude Code
+
+Enable an agent in config (`codingAgents.claude-code.enabled = true`), register a
+project, then:
+
+```text
+coding_agent_plan(agent:"claude-code", projectId:"my-app", task:"Plan SEO improvements")
+# review the plan, approve, then:
+coding_agent_start_task(agent:"claude-code", projectId:"my-app", task:"Implement the plan")
+# creates a work branch, runs the agent, then:
+coding_agent_get_diff(taskId) · coding_agent_run_validation(projectId)
+```
+
+Execution is risk-3 (approval required), runs on a fresh branch, warns on a dirty
+tree, and is followed by diff + validation. See [docs/coding-agents.md](docs/coding-agents.md).
+
+## Codex example
+
+Same flow with `agent:"codex"` once `codingAgents.codex.enabled = true` and the
+`codex` CLI is on PATH.
+
+## Article publishing
+
+- **Zenn**: GitHub-repo method — writes `articles/<slug>.md` with
+  `published:false`, can open a PR branch. (`zenn_*`)
+- **Qiita**: official API with `QIITA_TOKEN` from the vault; private-first.
+  (`qiita_*`)
+- **note**: draft-first local files; publishing requires the note-mcp adapter.
+  (`note_*`)
+
+Publish actions are **risk 4 (double approval)**. See [docs/articles.md](docs/articles.md).
+
+## Browser automation
+
+Playwright-based (optional peer dependency), using an **isolated profile** by
+default. `browser_open/screenshot/extract_text/click/type/...` — all risk 3.
+See [docs/browser.md](docs/browser.md).
+
+## Android ADB
+
+`adb_list_devices/screenshot/tap/swipe/input_text/logcat/install_apk/...`.
+Input/installs are risk 3 and audited. See [docs/adb.md](docs/adb.md).
+
+## OpenClaw adapter
+
+`openclaw_status/list_skills/run_skill/list_sessions/...` — bridges to a local
+`openclaw` CLI if installed, otherwise returns clear install guidance. Every call
+flows through the gateway's permission + approval + audit pipeline.
+
+## Desktop Commander adapter
+
+`desktop_commander_status/list_tools/run_tool` — gated bridge; tools are never
+exposed unmediated.
+
+## Existing MCP bridge
+
+Register downstream MCP servers (`mcp_server_register/list/status/...`) to bundle
+them behind the gateway's safety pipeline.
+
+## CLI
+
+```bash
+localant setup | start | stop | restart | status | doctor | update | uninstall
+localant tunnel status
+localant dashboard | logs
+localant approvals list | approve <id> [--session] | deny <id>
+localant skills list | info <name> | enable <name> | disable <name> | install <git-url> | validate <name> | publish <name>
+localant projects list | add <path> [--name <n>] | remove <id>
+localant secrets set <name> [value] | list | remove <name>
+```
+
+## Architecture
+
+A pnpm + TypeScript monorepo with project references:
+
+| Package | Responsibility |
+|---------|----------------|
+| `shared` | config schema, paths, risk model, redaction, types, logger |
+| `gateway` | stores, security guards, managers, tool registry, execution pipeline |
+| `mcp` | Streamable HTTP `/mcp`, auth, dashboard API |
+| `dashboard` | self-contained local dashboard |
+| `cli` | `setup`/`start`/`doctor`/… commands |
+| `skill-sdk` | `defineSkill` for external skill authors |
+
+See [docs/architecture.md](docs/architecture.md).
+
+## FAQ
+
+- **Does ChatGPT get a raw shell?** No. Only allowlisted commands run without
+  approval; anything else needs an explicit local approval.
+- **Where is my config?** `~/Library/Application Support/LocalAnt` (macOS),
+  `~/.config/LocalAnt` (Linux), `%APPDATA%/LocalAnt` (Windows).
+- **Do I need Claude Code/Codex/adb/Playwright?** Only for those specific tool
+  families; they degrade gracefully with install guidance.
+- **Is the tunnel safe?** A public tunnel exposes the gateway; the auth token is
+  required, the dashboard warns you, and you should stop the tunnel when idle.
+
+## Troubleshooting
+
+`localant doctor` diagnoses your environment. More in
+[docs/troubleshooting.md](docs/troubleshooting.md).
+
+## How to uninstall
+
+```bash
+localant uninstall          # prints steps
+localant uninstall --purge  # also deletes the config/data directory
+npm uninstall -g localant
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,87 @@
+# Security
+
+`LocalAnt` performs operations on your local machine on behalf of a
+remote model (ChatGPT). Security is the top design priority. This document
+describes the threat model and the controls that mitigate it.
+
+## Threat model
+
+| Actor / vector | Risk | Mitigation |
+|----------------|------|------------|
+| ChatGPT requests a destructive action | High | Risk levels + local approval queue; ChatGPT confirmation never trusted alone |
+| Prompt-injected ChatGPT tries to read secrets/credentials | High | Secret vault (encrypted), redaction, sensitive-path blocklist |
+| Path traversal / symlink escape | High | `PathGuard` resolves realpaths and re-checks allowlist + blocklist |
+| Shell injection / command chaining | High | `CommandGuard` rejects pipes/redirection/substitution; allowlist prefix match; hard blocklist |
+| Public tunnel exposure | Medium | Mandatory auth token; dashboard warnings; tunnel is opt-out |
+| Malicious third-party skill | Medium | Skills disabled by default; per-skill permission manifest; isolated subprocess execution; only declared secrets injected |
+| Secret leakage to logs/responses | Medium | Deep redaction of known secret values + token-shaped strings |
+
+## Default deny
+
+Nothing is permitted unless explicitly allowed:
+
+- **Filesystem**: only paths inside `security.allowedDirectories`. Sensitive
+  paths (`~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.config/gcloud`, Keychains, `/etc`,
+  `/var`, `/System`, `C:\Windows`, …) are always denied — even via symlink.
+- **Shell**: no raw shell. `shell_run_allowed_command` only accepts commands
+  matching the allowlist; pipes, redirection, chaining, and command
+  substitution are rejected. A hard blocklist (`sudo`, `rm -rf`, `dd`, `mkfs`,
+  `chmod 777`, `ssh`, `shutdown`, …) applies even to approved commands.
+- **Network/secrets/browser/adb/git/agent**: per-skill permission modes; tools
+  default to the least-privilege option.
+
+## Risk levels & approval
+
+| Risk | Meaning | Approval |
+|------|---------|----------|
+| 0 | read-only | none |
+| 1 | safe write draft | configurable (`approveRisk1`, default off) |
+| 2 | file modification | single approval |
+| 3 | shell / agent / network write | single approval |
+| 4 | destructive / publish / deploy | **double approval** |
+
+Approvals are managed **locally** (dashboard, CLI `approvals`, or the
+`approval_*` MCP tools). A risk-2+ tool call returns `approvalRequired` until a
+human approves it; once-approvals are consumed after a single use.
+
+## Filesystem safety
+
+- Allowed-directory allowlist + sensitive-path blocklist.
+- Path traversal (`..`) and symlink traversal prevention (realpath re-check).
+- Backup-before-write for modifications/deletes; `fs_list_backups` /
+  `fs_restore_backup`.
+- Max file size and binary-file guard on reads; draft writes refuse overwrite.
+
+## Shell safety
+
+- Allowlist prefix matching; pipeline/redirection/chaining/substitution rejected.
+- Hard blocklist enforced even after approval.
+- No shell interpreter — validated commands are split to argv and executed
+  directly with a timeout and output cap.
+
+## Secret safety
+
+- Secrets stored in an AES-256-GCM encrypted vault keyed from the local token.
+- Listing returns **names only**; values are never displayed.
+- Tool output and audit entries are deep-redacted for known secret values and
+  token-shaped strings.
+- Skills receive only the secret values they declare in their manifest, passed
+  to an isolated subprocess — never the vault itself.
+
+## Skill safety
+
+- Generated and git-installed skills are saved **disabled**.
+- Each skill ships a permission manifest and risk level, surfaced before enable.
+- Skills execute in an isolated Node subprocess.
+- `skill_validate` checks manifest + required files before enabling.
+
+## Audit
+
+Every tool call is appended to `audit/audit.jsonl` with timestamp, tool, caller,
+risk, redacted input/output summaries, approval result, duration, and error.
+
+## Reporting vulnerabilities
+
+Please open a private security advisory on the repository or email the
+maintainers rather than filing a public issue. Include reproduction steps and
+affected versions. We aim to acknowledge within a few days.

package/examples/skills/hello-world/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## 0.1.0
+- Initial example skill with a single `hello` tool.

package/examples/skills/hello-world/LICENSE

@@ -0,0 +1 @@
+MIT License — see repository root LICENSE.

package/examples/skills/hello-world/README.md

@@ -0,0 +1,20 @@
+# hello-world
+
+A minimal example local skill for `LocalAnt`.
+
+## Permissions
+None. This skill only echoes a greeting — no filesystem, shell, network, or secret access.
+
+- risk level: 0 (read-only)
+
+## Usage
+Once enabled, ask ChatGPT:
+
+> Use the hello-world skill to greet "Yuga".
+
+ChatGPT calls `skill_run` with `{ name: "hello-world", tool: "hello", input: { name: "Yuga" } }`.
+
+## Develop
+```bash
+pnpm test   # runs tests/index.test.ts
+```

package/examples/skills/hello-world/examples/example.json

@@ -0,0 +1 @@
+{ "name": "Yuga" }

package/examples/skills/hello-world/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@localant-skill/hello-world",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@localant/skill-sdk": "workspace:*"
+  }
+}

package/examples/skills/hello-world/skill.json

@@ -0,0 +1,32 @@
+{
+  "name": "hello-world",
+  "displayName": "Hello World",
+  "version": "0.1.0",
+  "description": "A minimal example local skill that greets a name.",
+  "author": "LocalAnt",
+  "license": "MIT",
+  "entry": "src/index.ts",
+  "riskLevel": 0,
+  "permissions": {
+    "filesystem": { "mode": "none", "allowedDirectories": [] },
+    "shell": { "mode": "none", "allowedCommands": [] },
+    "network": { "mode": "none", "allowedHosts": [] },
+    "secrets": [],
+    "browser": "none",
+    "adb": "none",
+    "git": "none",
+    "agent": "none"
+  },
+  "tools": [
+    {
+      "name": "hello",
+      "description": "Say hello to a name.",
+      "riskLevel": 0,
+      "inputSchema": {
+        "type": "object",
+        "properties": { "name": { "type": "string" } },
+        "required": ["name"]
+      }
+    }
+  ]
+}

package/examples/skills/hello-world/src/index.ts

@@ -0,0 +1,19 @@
+import { defineSkill, z } from "@localant/skill-sdk";
+
+export default defineSkill({
+  name: "hello-world",
+  displayName: "Hello World",
+  description: "A minimal example local skill.",
+  version: "0.1.0",
+  tools: {
+    hello: {
+      description: "Say hello to a name.",
+      riskLevel: 0,
+      inputSchema: z.object({ name: z.string() }),
+      handler: async ({ name }, ctx) => {
+        ctx.log(`greeting ${name}`);
+        return { content: `Hello, ${name}! 👋 (from your local PC)` };
+      },
+    },
+  },
+});

package/examples/skills/hello-world/tests/index.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from "vitest";
+import skill from "../src/index";
+
+describe("hello-world skill", () => {
+  it("exposes the hello tool", () => {
+    expect(skill.name).toBe("hello-world");
+    expect(skill.tools.hello).toBeDefined();
+  });
+
+  it("greets a name", async () => {
+    const ctx = { getSecret: async () => undefined, workspaceDir: ".", log: () => {} };
+    const out = (await skill.tools.hello.handler({ name: "Yuga" }, ctx)) as { content: string };
+    expect(out.content).toContain("Hello, Yuga!");
+  });
+
+  it("validates input", () => {
+    expect(() => skill.tools.hello.inputSchema.parse({})).toThrow();
+  });
+});

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "localant",
+  "version": "1.0.0",
+  "private": false,
+  "description": "LocalAnt — Use ChatGPT as the brain and your local computer as the hands. A safe, permissioned local MCP Gateway for ChatGPT.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "localant": "packages/cli/dist/bin.js"
+  },
+  "files": [
+    "packages/*/dist/**",
+    "packages/*/package.json",
+    "examples/skills/**",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean && rimraf packages/*/dist",
+    "dev": "tsc -b --watch",
+    "typecheck": "tsc -b --noEmit false",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "validate": "pnpm build && pnpm test",
+    "start": "node packages/cli/dist/bin.js start",
+    "setup": "node packages/cli/dist/bin.js setup"
+  },
+  "keywords": [
+    "chatgpt",
+    "mcp",
+    "model-context-protocol",
+    "local-first",
+    "gateway",
+    "skills",
+    "claude-code",
+    "codex",
+    "automation",
+    "openclaw",
+    "localant"
+  ],
+  "devDependencies": {
+    "@localant/gateway": "workspace:*",
+    "@localant/mcp": "workspace:*",
+    "@localant/shared": "workspace:*",
+    "@localant/skill-sdk": "workspace:*",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.0",
+    "@typescript-eslint/eslint-plugin": "^8.18.0",
+    "@typescript-eslint/parser": "^8.18.0",
+    "eslint": "^9.17.0",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "packageManager": "pnpm@11.5.1"
+}

package/packages/cli/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/packages/cli/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}