A secure local coding workspace for ChatGPT and other MCP hosts.
\r\n\r\n
\r\n \r\n \r\n \r\n \r\n
\r\n\r\nLocalSpace lets ChatGPT, Claude, or another MCP-capable client work directly in\r\nselected folders on your own machine. It exposes file inspection, scoped edits,\r\ncode search, Git review, command execution, validation summaries, and handoff\r\ntools through a self-hosted MCP server.\r\n\r\nUse it when you want a Codex-style loop in ChatGPT: inspect the repository, read\r\nproject instructions, make focused changes, run local tests, review diffs, and\r\ncontinue long tasks across chat windows.\r\n\r\n
\r\n \r\n
\r\n\r\n> **Security note**\r\n>\r\n> LocalSpace is remote access to selected local folders. Your files stay on your\r\n> machine unless a connected MCP client explicitly asks LocalSpace to read or\r\n> modify them through tool calls. Only connect clients you trust, keep the Owner\r\n> password private, and keep your allowed roots narrow.\r\n\r\n---\r\n\r\n## Why LocalSpace?\r\n\r\nLocalSpace is designed for hybrid human + AI coding sessions where the model is\r\ninside your real development environment, but every capability remains explicit\r\nand inspectable.\r\n\r\n- **Local-first coding**: work with your actual projects, package manager, Git\r\n repository, scripts, and terminal.\r\n- **Workspace-based access**: open one approved folder or managed worktree, then\r\n reuse the returned `workspaceId` for all later operations.\r\n- **Codex-style editing**: use `read`, `apply_patch`, `exec_command`,\r\n `write_stdin`, `changes`, and dedicated `git_*` tools.\r\n- **Fast code orientation**: use `project_map`, `entrypoints`, `symbols`,\r\n `imports`, `references`, and `code_map` before changing unfamiliar code.\r\n- **Workflow guidance**: use `doctor`, `workspace_info`, `next_steps`,\r\n `validate_plan`, `review_checklist`, `validation_summary`, `task_summary`,\r\n `final_report`, and `handoff_summary` to keep long sessions grounded.\r\n- **Safety rails**: use filesystem allowlists, OAuth owner approval, Host header\r\n checks, sensitive-path protection, command risk warnings, danger-command\r\n approval tokens, and audit logs.\r\n\r\nLocalSpace does **not** replace your judgment. Shell access is intentionally\r\npowerful, so treat a connected MCP client like a trusted coding partner with\r\naccess to your machine.\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n### 1. Install requirements\r\n\r\nLocalSpace requires:\r\n\r\n- Node `>=22.19 <27`\r\n- npm\r\n- Git\r\n- a public HTTPS URL that forwards to the local LocalSpace server\r\n\r\nOn Windows, portable commands such as `node`, `npm`, and `git` work directly.\r\nBash-specific commands still require Git Bash, WSL, MSYS2, Cygwin Bash, or an\r\nexplicit shell configured with `LOCALSPACE_SHELL`.\r\n\r\n### 2. Install LocalSpace\r\n\r\nInstall the published package:\r\n\r\n```bash\r\nnpm install -g @alan512/localspace\r\n```\r\n\r\nOr, if you are developing LocalSpace from this checkout:\r\n\r\n```bash\r\nnpm install\r\nnpm run build\r\n```\r\n\r\n### 3. Initialize LocalSpace\r\n\r\n```bash\r\nlocalspace init\r\n```\r\n\r\nFrom a local checkout, use `node dist/cli.js init` instead.\r\n\r\nDuring setup, choose:\r\n\r\n- the local folders that MCP clients may open as workspaces\r\n- the local port, usually `7676` or `7680`\r\n- the public HTTPS base URL for your tunnel or reverse proxy\r\n\r\nEnter the public base URL as an origin only, without `/mcp`:\r\n\r\n```text\r\nhttps://your-tunnel-host.example.com\r\n```\r\n\r\nThe Owner password is printed during setup and stored in:\r\n\r\n```text\r\n~/.localspace/auth.json\r\n```\r\n\r\nKeep this password private. LocalSpace also keeps a backward-compatible fallback\r\nfor legacy auth files from earlier installs.\r\n\r\n### 4. Start your tunnel\r\n\r\nLocalSpace does not create the public tunnel for you. Use Cloudflare Tunnel,\r\nngrok, Pinggy, Tailscale Funnel, or another HTTPS reverse proxy.\r\n\r\nPoint the tunnel to your local server, for example:\r\n\r\n```text\r\nhttp://127.0.0.1:7680\r\n```\r\n\r\nThen configure your MCP client with:\r\n\r\n```text\r\nhttps://your-tunnel-host.example.com/mcp\r\n```\r\n\r\n### 5. Start LocalSpace\r\n\r\n```bash\r\nlocalspace serve\r\n```\r\n\r\nFrom a local checkout, use `node dist/cli.js serve` instead.\r\n\r\nWhen the MCP client connects, LocalSpace shows an Owner approval page. Enter the\r\nOwner password only when you intentionally want that client to access this\r\nserver.\r\n\r\n### 6. Open a project from ChatGPT\r\n\r\nAsk your MCP client to open one of the approved folders:\r\n\r\n```text\r\n@localspace Open ~/work/my-project and inspect the current git status.\r\n```\r\n\r\nFor long or risky changes, prefer an isolated managed worktree:\r\n\r\n```text\r\n@localspace Open ~/work/my-project in worktree mode and implement the next task.\r\n```\r\n\r\n---\r\n\r\n## Common Commands\r\n\r\n```bash\r\n# Check local runtime, config, Git, shell, and dependency health\r\nlocalspace doctor\r\n\r\n# Start the MCP server\r\nlocalspace serve\r\n\r\n# Start with a temporary public URL override\r\nLOCALSPACE_PUBLIC_BASE_URL=\"https://new-tunnel.example.com\" localspace serve\r\n\r\n# Persist a stable public URL\r\nlocalspace config set publicBaseUrl https://localspace.example.com\r\n```\r\n\r\nIf you are running from a local checkout, replace `localspace` with\r\n`node dist/cli.js` after running `npm run build`.\r\n\r\n---\r\n\r\n## Tool Surface\r\n\r\nLocalSpace is designed around the default `hybrid` tool surface. It combines\r\nsafe workspace inspection, Codex-style patching, process tools, code navigation,\r\nGit helpers, and workflow summaries for ChatGPT coding sessions.\r\n\r\n`LOCALSPACE_TOOL_MODE` still exists for compatibility and advanced experiments,\r\nbut normal users should keep the default `hybrid` mode.\r\n\r\n| Mode | Status | Best for |\r\n| --- | --- | --- |\r\n| `hybrid` | Default and recommended | ChatGPT coding sessions with Codex-style edits, process tools, code navigation, Git helpers, and workflow summaries. |\r\n| `codex` | Experimental compatibility | A smaller Codex-like surface: workspace, read, patch, command, process, changes, and Git tools. |\r\n| `full` | Legacy compatibility | Broader dedicated inspection/search/edit tools plus Git and workflow helpers. |\r\n| `minimal` | Legacy compatibility | A small compatibility surface for hosts that prefer simple read/write/bash-style tools. |\r\n\r\nExample:\r\n\r\n```bash\r\nLOCALSPACE_TOOL_MODE=\"hybrid\" node dist/cli.js serve\r\n```\r\n\r\nSee [`docs/configuration.md`](docs/configuration.md) for the complete reference.\r\n\r\nLocalSpace also ships built-in workflow skills. `open_workspace` advertises only\r\ntheir names, descriptions, and `SKILL.md` paths; the model should read the\r\nmatching skill only when the current task needs that workflow. This keeps\r\nworkflow guidance progressively loaded while the `hybrid` tool surface remains\r\nthe single recommended default.\r\n\r\n---\r\n\r\n## What ChatGPT Can Do\r\n\r\n\r\nIn the default `hybrid` mode, ChatGPT can:\r\n\r\n- open an approved checkout or managed worktree with `open_workspace`\r\n- inspect project state with `doctor`, `workspace_info`, and `entrypoints`\r\n- read files directly with `read`\r\n- map unfamiliar projects with `project_map` and `code_map`\r\n- search code with `grep`, `glob`, `ls`, `symbols`, `imports`, and `references`\r\n- edit files with `apply_patch`\r\n- run commands with `exec_command` and interact with running processes through\r\n `write_stdin`\r\n- review changes with `changes`, `git_status`, `git_diff`, and `git_log`\r\n- stage and commit explicit files with `git_add` and `git_commit` when the user\r\n asks for it\r\n- summarize progress with `session_summary`, `validation_summary`,\r\n `task_summary`, `final_report`, and `handoff_summary`\r\n\r\nThe workflow tools are intentionally read-only unless their names clearly imply\r\nmutation, such as `apply_patch`, `exec_command`, `git_add`, or `git_commit`.\r\n\r\n---\r\n\r\n## Security Model\r\n\r\nLocalSpace has multiple safety layers, but it is still a tool for trusted local\r\ndevelopment access.\r\n\r\n| Layer | Purpose |\r\n| --- | --- |\r\n| Filesystem allowlist | Only configured roots can be opened as workspaces. |\r\n| OAuth owner approval | A connecting MCP client must be approved with your Owner password. |\r\n| Host allowlist | LocalSpace derives allowed hosts from local and public configuration. |\r\n| Sensitive path protection | Write-like tools block `.env`, Git config/hooks, secret-like files, LocalSpace state paths, home roots, and system directories. |\r\n| Command warnings | Risky shell patterns are surfaced before or with command execution. |\r\n| Danger-command approval | High-risk commands require an explicit one-time approval token. |\r\n| Audit log | Important coding actions are recorded for review and session summaries. |\r\n\r\nGood allowed roots are narrow project folders such as:\r\n\r\n```text\r\n~/work\r\n~/personal/open-source\r\nC:\\Users\\alice\\dev\r\n```\r\n\r\nAvoid broad roots such as `~`, `/`, or `C:\\`.\r\n\r\nRead more in [`docs/security.md`](docs/security.md).\r\n\r\n---\r\n\r\n## ChatGPT Workflow\r\n\r\nA strong LocalSpace session usually follows this loop:\r\n\r\n1. Open the target folder once with `open_workspace`.\r\n2. Read returned `AGENTS.md` or equivalent project instructions.\r\n3. Inspect the repo with `workspace_info`, `entrypoints`, `project_map`, or\r\n `code_map`.\r\n4. Make small, scoped edits with `apply_patch`.\r\n5. Run the most relevant validation commands.\r\n6. Review `changes` or `git_diff` before summarizing.\r\n7. Use `final_report` or `handoff_summary` at natural stopping points.\r\n\r\nFor detailed model-facing guidance, see\r\n[`docs/chatgpt-coding-workflow.md`](docs/chatgpt-coding-workflow.md).\r\n\r\n---\r\n\r\n## Documentation\r\n\r\n- [`docs/setup.md`](docs/setup.md): setup walkthrough\r\n- [`docs/configuration.md`](docs/configuration.md): commands, environment\r\n variables, tool modes, widgets, skills, and logging\r\n- [`docs/security.md`](docs/security.md): security model and operational cautions\r\n- [`docs/chatgpt-coding-workflow.md`](docs/chatgpt-coding-workflow.md): how an\r\n MCP host should use LocalSpace during coding tasks\r\n- [`docs/structured-content.md`](docs/structured-content.md): structured output\r\n returned by navigation, Git, diagnostics, and workflow tools\r\n- [`docs/gotchas.md`](docs/gotchas.md): common setup and workflow pitfalls\r\n\r\n---\r\n\r\n## Local Development\r\n\r\nFor working on LocalSpace itself:\r\n\r\n```bash\r\nnpm install --include=dev\r\nnpm run dev\r\nnpm run typecheck\r\nnpm test\r\nnpm run build\r\nnpm run start\r\n```\r\n\r\nBefore finalizing changes, run at least:\r\n\r\n```bash\r\nnpm run typecheck\r\nnpm test\r\n```\r\n\r\n---\r\n\r\n## Credits\r\n\r\nLocalSpace started as a fork of\r\n[DevSpace](https://github.com/Waishnav/devspace) by\r\n[Waishnav](https://x.com/wshxnv). The original project demonstrated a practical\r\nway to bring local coding workflows to MCP hosts.\r\n\r\nLocalSpace builds on that foundation with its own branding, CLI/config paths,\r\nhybrid tool modes, structured output, code navigation, Git helpers, command\r\nsafety, audit logs, workflow summaries, and long-session handoff support.\r\n\r\n## License\r\n\r\nMIT. See [`LICENSE`](LICENSE).\r\n","readmeFilename":"README.md"}
![\"LocalSpace](\"docs/assets/localspace-logo-light.svg\"){kind=logo}
\r\n ![\"npm\"](\"https://img.shields.io/npm/v/@alan512/localspace?style=flat-square\")
![\"CI\"](\"https://img.shields.io/github/actions/workflow/status/Alan-512/localspace/ci.yml?style=flat-square&branch=main\")
![\"License\"](\"https://img.shields.io/badge/license-MIT-blue?style=flat-square\"){kind=icon}
![\"MCP\"](\"https://img.shields.io/badge/MCP-local%20coding%20workspace-7c3aed?style=flat-square\"){kind=icon}
![\"LocalSpace](\"docs/assets/localspace-feature-showcase.png\")
\r\n