Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix: documentation and small changes

Luigi Agosti3ef76b51d24b
diff --git a/README.md b/README.md
index 920703a7..a99149f7 100644
--- a/README.md
+++ b/README.md
@@ -72,7 +72,7 @@ See the full guide: [docs/guides/security.md](docs/guides/security.md)
With the daemon installed and an agent skill configured, an agent can execute tasks like:
```
-"What are the main news about trump on news.com?"
+"What are the main news about aliens on news.com?"
```
PinchTab exposes browser tools that allow agents to navigate pages, extract structured content, and interact with the DOM without wasting tokens on raw HTML or images.
@@ -160,6 +160,21 @@ curl -fsSL https://pinchtab.com/install.sh | bash
npm install -g pinchtab
```
+### Shell Completion
+
+Generate and install shell completions after `pinchtab` is on your `PATH`:
+
+```bash
+# Generate and install zsh completions
+pinchtab completion zsh > "${fpath[1]}/_pinchtab"
+
+# Generate bash completions
+pinchtab completion bash > /etc/bash_completion.d/pinchtab
+
+# Generate fish completions
+pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish
+```
+
**Docker:**
```bash
docker run -d \
@@ -315,6 +330,8 @@ curl -s -X POST http://localhost:9867/instances/start \
curl http://localhost:9867/instances
```
+See [chrome-files.md](chrome-files.md) for technical details on how PinchTab manages Chrome user data directories and ensures isolation between parallel instances.
+
---
## Development
diff --git a/docs/get-started.md b/docs/get-started.md
index ec609fe3..12379f76 100644
--- a/docs/get-started.md
+++ b/docs/get-started.md
@@ -52,6 +52,21 @@ go build -o pinchtab ./cmd/pinchtab
**[Full build guide ->](architecture/building.md)**
+## Shell Completion
+
+After installation, you can generate shell completions from the CLI:
+
+```bash
+# Generate and install zsh completions
+pinchtab completion zsh > "${fpath[1]}/_pinchtab"
+
+# Generate bash completions
+pinchtab completion bash > /etc/bash_completion.d/pinchtab
+
+# Generate fish completions
+pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish
+```
+
---
## Quick start
diff --git a/docs/implementations/chrome-files.md b/docs/implementations/chrome-files.md
new file mode 100644
index 00000000..4df09ba0
--- /dev/null
+++ b/docs/implementations/chrome-files.md
@@ -0,0 +1,52 @@
+# Chrome User Data Directories & Profiles
+
+PinchTab manages Chrome instances using dedicated **User Data Directories** (profiles). This document explains how these directories are resolved, how locks are managed, and how to handle parallel browser instances.
+
+## Profile Resolution
+
+PinchTab determines the Chrome `--user-data-dir` (profile) using the following precedence:
+
+1. **Explicit `ProfileDir`**: If a specific path is provided in the configuration or as a flag, PinchTab uses that exact directory.
+2. **Named Profile**: If a profile name is provided (e.g., via the dashboard or CLI), PinchTab resolves it to a subdirectory within the `ProfilesBaseDir`.
+3. **Default Profile**: If no profile is specified, it defaults to `~/.config/pinchtab/profiles/default` (on Linux/macOS).
+
+## The Singleton Model
+
+Chrome enforces a **Singleton** model per User Data Directory. This means:
+* Only **one** Chrome process can use a specific profile directory at any given time.
+* If a second process attempts to use the same directory, Chrome will either fail to start or (in some configurations) attempt to open a new window in the existing process.
+
+PinchTab adds an additional layer of protection using a `pinchtab.pid` file within the profile directory to ensure that only one PinchTab instance manages a specific profile.
+
+## New Headless & Parallel Instances
+
+With the introduction of **New Headless mode** (`--headless=new`), Chrome's profile sharing behavior has become stricter:
+* **No Sharing**: You cannot reuse the same `--user-data-dir` across multiple concurrent instances.
+* **Separate Directories Required**: Parallel browsers **must** use separate directories to avoid random startup errors and lock conflicts.
+
+### Headless Auto-Fallback
+To support parallel automation tasks, PinchTab implements an **automatic fallback for headless instances**:
+1. If a headless instance tries to start using a profile that is already locked by another PinchTab process, it will **automatically create a unique temporary directory** (e.g., `/tmp/pinchtab-profile-*`).
+2. This allows you to run multiple headless tasks in parallel without manually managing profile paths.
+
+### Manual Parallelism (Headed Mode)
+In **headed mode**, PinchTab does *not* automatically fall back to a temporary directory (to avoid losing user session data unexpectedly). If you need to run multiple headed browsers in parallel, you must:
+* Use different named profiles.
+* Explicitly provide a unique `--user-data-dir` for each instance.
+
+## Best Practices for AI Agents
+
+When building agents that use PinchTab, follow these guidelines:
+
+* **Persistence**: Use named profiles (e.g., `agent-alpha`, `agent-beta`) if you need the browser to remember logins, cookies, or history across sessions.
+* **Isolation**: For one-off tasks or high-concurrency scraping, rely on the default headless mode which handles directory isolation automatically if conflicts occur.
+* **Cleanup**: If you manually create temporary directories, ensure they are cleaned up after the task is complete to avoid filling up disk space.
+
+## Troubleshooting
+
+If you see the error `"The profile appears to be in use by another Chromium process"`:
+1. **Check for active instances**: Ensure you don't have another PinchTab or Chrome process already using that profile.
+2. **Stale Locks**: If no process is active, PinchTab will attempt to automatically clear stale `SingletonLock` files on the next startup.
+3. **Manual Fix**: In rare cases, you may need to manually remove the `SingletonLock` file from the profile directory.
+
+For more details on how PinchTab recovers from crashes, see [Chrome Profile Lock Recovery](docs/implementations/chrome-profile-lock-recovery.md).
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index c9a5c29f..f0853e70 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -76,9 +76,25 @@ These are the main local-control commands surfaced in the menu:
| `pinchtab daemon` | Show daemon status and manage the background service |
| `pinchtab config` | Open the interactive config overview/editor |
| `pinchtab security` | Review or change the current security posture |
+| `pinchtab completion <shell>` | Generate shell completion scripts for `bash`, `zsh`, `fish`, or `powershell` |
| `pinchtab bridge` | Start the single-instance bridge runtime |
| `pinchtab mcp` | Start the stdio MCP server |
+## Shell Completion
+
+Use the built-in completion command to generate shell-specific scripts:
+
+```bash
+# Generate and install zsh completions
+pinchtab completion zsh > "${fpath[1]}/_pinchtab"
+
+# Generate bash completions
+pinchtab completion bash > /etc/bash_completion.d/pinchtab
+
+# Generate fish completions
+pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish
+```
+
## Browser Shortcuts
The most common browser control shortcuts are top-level commands:
diff --git a/internal/cli/report/security.go b/internal/cli/report/security.go
index 66d6aad6..37f75c86 100644
--- a/internal/cli/report/security.go
+++ b/internal/cli/report/security.go
@@ -52,12 +52,6 @@ func AssessSecurityPosture(cfg *config.RuntimeConfig) SecurityPosture {
Passed: len(cfg.EnabledSensitiveEndpoints()) == 0,
Detail: formatEndpointStatus(cfg.EnabledSensitiveEndpoints()),
},
- {
- ID: "attach_disabled",
- Label: "attach endpoint",
- Passed: !cfg.AttachEnabled,
- Detail: map[bool]string{true: "disabled", false: "enabled"}[!cfg.AttachEnabled],
- },
{
ID: "attach_local_only",
Label: "attach host scope",
@@ -196,19 +190,12 @@ func AssessSecurityWarnings(cfg *config.RuntimeConfig) []SecurityWarning {
}
}
- if cfg.AttachEnabled {
+ if attachAllowsNonLocalHosts(cfg.AttachAllowHosts) {
warnings = append(warnings, SecurityWarning{
- ID: "attach_enabled",
- Message: "attach endpoint enabled",
- Attrs: []any{"hint", "only attach to Chrome instances you trust"},
+ ID: "attach_external_hosts",
+ Message: "attach allowHosts includes non-local hosts",
+ Attrs: []any{"allowHosts", cfg.AttachAllowHosts, "hint", "keep security.attach.allowHosts limited to local addresses unless external Chrome instances are intentional"},
})
- if attachAllowsNonLocalHosts(cfg.AttachAllowHosts) {
- warnings = append(warnings, SecurityWarning{
- ID: "attach_external_hosts",
- Message: "attach allowHosts includes non-local hosts",
- Attrs: []any{"allowHosts", cfg.AttachAllowHosts, "hint", "keep security.attach.allowHosts limited to local addresses unless external Chrome instances are intentional"},
- })
- }
}
return warnings
@@ -264,9 +251,9 @@ func securityPostureLevel(passed, total int) string {
switch {
case passed == total:
return "LOCKED"
- case passed >= total-2:
+ case passed >= total-1:
return "GUARDED"
- case passed >= total/2:
+ case passed >= 3:
return "ELEVATED"
default:
return "EXPOSED"
diff --git a/internal/cli/report/security_test.go b/internal/cli/report/security_test.go
index 8132617c..e22f5e31 100644
--- a/internal/cli/report/security_test.go
+++ b/internal/cli/report/security_test.go
@@ -57,7 +57,6 @@ func TestAssessSecurityWarnings(t *testing.T) {
"idpi_whitelist_not_set",
"idpi_warn_mode",
"idpi_content_protection_disabled",
- "attach_enabled",
"attach_external_hosts",
} {
if !ids[expected] {
@@ -147,8 +146,8 @@ func TestAssessSecurityPosture(t *testing.T) {
}
posture := assessSecurityPosture(cfg)
- if posture.Passed >= posture.Total/2 {
- t.Fatalf("expected exposed posture below half-score, got %d/%d", posture.Passed, posture.Total)
+ if posture.Passed >= 3 {
+ t.Fatalf("expected exposed posture below 3 passed checks, got %d/%d", posture.Passed, posture.Total)
}
if posture.Level != "EXPOSED" {
t.Fatalf("expected EXPOSED posture, got %q", posture.Level)
diff --git a/internal/cli/report/startup.go b/internal/cli/report/startup.go
index b704e824..f9857f2a 100644
--- a/internal/cli/report/startup.go
+++ b/internal/cli/report/startup.go
@@ -162,7 +162,7 @@ func SecurityLevelColor(level string) string {
case "GUARDED":
return string(colorWarning)
case "ELEVATED":
- return string(colorDanger)
+ return string(colorWarning)
default:
return string(colorDanger)
}
diff --git a/internal/cli/report/startup_test.go b/internal/cli/report/startup_test.go
index 1e30561b..a941c749 100644
--- a/internal/cli/report/startup_test.go
+++ b/internal/cli/report/startup_test.go
@@ -11,7 +11,7 @@ func TestSecurityLevelColor(t *testing.T) {
}{
{level: "LOCKED", want: string(colorSuccess)},
{level: "GUARDED", want: string(colorWarning)},
- {level: "ELEVATED", want: string(colorDanger)},
+ {level: "ELEVATED", want: string(colorWarning)},
{level: "EXPOSED", want: string(colorDanger)},
{level: "UNKNOWN", want: string(colorDanger)},
}
diff --git a/internal/config/config_file.go b/internal/config/config_file.go
index f54b957b..5d0b56ac 100644
--- a/internal/config/config_file.go
+++ b/internal/config/config_file.go
@@ -25,6 +25,7 @@ func DefaultFileConfig() FileConfig {
allowDownload := false
allowUpload := false
maxRedirects := -1
+ attachEnabled := true
return FileConfig{
ConfigVersion: CurrentConfigVersion,
Server: ServerConfig{
@@ -49,6 +50,7 @@ func DefaultFileConfig() FileConfig {
AllowUpload: &allowUpload,
MaxRedirects: &maxRedirects,
Attach: AttachConfig{
+ Enabled: &attachEnabled,
AllowHosts: []string{"127.0.0.1", "localhost", "::1"},
AllowSchemes: []string{"ws", "wss"},
},
diff --git a/internal/config/config_load.go b/internal/config/config_load.go
index bf0d8412..7ea7ac3d 100644
--- a/internal/config/config_load.go
+++ b/internal/config/config_load.go
@@ -64,7 +64,7 @@ func Load() *RuntimeConfig {
RestartStableAfter: 5 * time.Minute,
// Attach defaults
- AttachEnabled: false,
+ AttachEnabled: true,
AttachAllowHosts: []string{"127.0.0.1", "localhost", "::1"},
AttachAllowSchemes: []string{"ws", "wss"},
diff --git a/internal/config/config_load_test.go b/internal/config/config_load_test.go
index f8c71611..fabbb035 100644
--- a/internal/config/config_load_test.go
+++ b/internal/config/config_load_test.go
@@ -68,8 +68,8 @@ func TestLoadConfigDefaults(t *testing.T) {
if cfg.TabEvictionPolicy != "close_lru" {
t.Errorf("default TabEvictionPolicy = %v, want close_lru", cfg.TabEvictionPolicy)
}
- if cfg.AttachEnabled {
- t.Errorf("default AttachEnabled = %v, want false", cfg.AttachEnabled)
+ if !cfg.AttachEnabled {
+ t.Errorf("default AttachEnabled = %v, want true", cfg.AttachEnabled)
}
if len(cfg.AttachAllowSchemes) != 2 || cfg.AttachAllowSchemes[0] != "ws" || cfg.AttachAllowSchemes[1] != "wss" {
t.Errorf("default AttachAllowSchemes = %v, want [ws wss]", cfg.AttachAllowSchemes)
diff --git a/npm/README.md b/npm/README.md
index 9b8bbd4e..485a5daf 100644
--- a/npm/README.md
+++ b/npm/README.md
@@ -127,6 +127,21 @@ pinchtab --version
pinchtab --help
```
+### Shell Completion
+
+After installing the CLI globally, you can generate shell completions:
+
+```bash
+# Generate and install zsh completions
+pinchtab completion zsh > "${fpath[1]}/_pinchtab"
+
+# Generate bash completions
+pinchtab completion bash > /etc/bash_completion.d/pinchtab
+
+# Generate fish completions
+pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish
+```
+
### Using a Custom Binary
For Docker, development, or other custom setups: