{"id":36713625,"url":"https://github.com/juanibiapina/gob","last_synced_at":"2026-02-07T22:01:19.031Z","repository":{"id":324779895,"uuid":"1098510574","full_name":"juanibiapina/gob","owner":"juanibiapina","description":"Process manager for AI agents (and humans)","archived":false,"fork":false,"pushed_at":"2026-02-04T14:25:04.000Z","size":6146,"stargazers_count":36,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-04T21:15:45.937Z","etag":null,"topics":["ai-tools","background-jobs","bubbletea","claude-code","cli","cli-app","codex","crush","developer-experience","developer-tools","go","golang","opencode","process-manager","terminal","terminal-utilities","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/juanibiapina.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-17T19:34:32.000Z","updated_at":"2026-02-04T16:21:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/juanibiapina/gob","commit_stats":null,"previous_names":["juanibiapina/job"],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/juanibiapina/gob","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juanibiapina%2Fgob","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juanibiapina%2Fgob/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juanibiapina%2Fgob/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juanibiapina%2Fgob/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/juanibiapina","download_url":"https://codeload.github.com/juanibiapina/gob/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juanibiapina%2Fgob/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29209823,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-07T21:35:21.898Z","status":"ssl_error","status_checked_at":"2026-02-07T21:35:20.106Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","background-jobs","bubbletea","claude-code","cli","cli-app","codex","crush","developer-experience","developer-tools","go","golang","opencode","process-manager","terminal","terminal-utilities","tui"],"created_at":"2026-01-12T11:51:27.570Z","updated_at":"2026-02-07T22:01:19.016Z","avatar_url":"https://github.com/juanibiapina.png","language":"Go","funding_links":[],"categories":["Tools \u0026 Utilities"],"sub_categories":[],"readme":"# gob\n\n[![GitHub Release](https://img.shields.io/github/release/juanibiapina/gob.svg)](https://github.com/juanibiapina/gob/releases)\n[![Go Report Card](https://goreportcard.com/badge/github.com/juanibiapina/gob)](https://goreportcard.com/report/github.com/juanibiapina/gob)\n![Go](https://img.shields.io/github/languages/top/juanibiapina/gob)\n![Languages](https://img.shields.io/github/languages/count/juanibiapina/gob)\n[![Contributors](https://img.shields.io/github/contributors/juanibiapina/gob)](https://github.com/juanibiapina/gob/graphs/contributors)\n![Last Commit](https://img.shields.io/github/last-commit/juanibiapina/gob)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/juanibiapina/gob)\n\n\u003e Process manager for AI agents (and humans).\n\n`gob` (pronounced job, of course) is a CLI for managing background processes with a shared interface for you and your AI coding agent.\n\nStart a dev server with Claude Code, check its logs yourself. Or vice-versa. The agent can monitor what you started. Everyone has the same view.\n\nNo more \"can you check if that's still running?\" No more copy-pasting logs through chat. Just direct access to your processes, for everyone.\n\n![TUI Screenshot](assets/tui.png)\n\n## Features\n\n- **Interactive TUI** - Full-screen terminal interface with real-time job status\n- **Real-time log streaming** - Follow stdout/stderr from CLI, TUI, or AI agents without copying output\n- **AI agent friendly** - Shared view of all processes for you and your coding agent\n- **Real-time sync** - Changes from CLI instantly appear in TUI, and vice-versa\n- **Per-directory jobs** - Jobs are scoped to directories, keeping projects organized\n- **Process lifecycle control** - Start, stop, restart, send signals to any job\n- **Port monitoring** - Inspect listening ports across a job's entire process tree\n- **Reliable shutdowns** - Stop, restart, and shutdown verify every child process in the tree is gone\n- **Job persistence** - Jobs survive daemon restarts with SQLite-backed state\n- **Run history** - Track execution history, statistics, and progress estimates for repeated commands\n- **Stuck detection** - Automatically detects jobs that may be stuck and returns early, while the job continues running\n- **Blocked jobs** - Prevent AI coding agents from accidentally running dangerous commands\n\n## Installation\n\n\u003cdetails\u003e\n\u003csummary\u003eHomebrew\u003c/summary\u003e\n\n```bash\nbrew tap juanibiapina/taps\nbrew install gob\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eGo Install\u003c/summary\u003e\n\n```bash\ngo install github.com/juanibiapina/gob@latest\n```\n\nRequirements:\n- Go 1.25.4 or later\n\nThe binary will be installed to `$GOPATH/bin` (or `$GOBIN` if set). Make sure this directory is in your `PATH`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eNix\u003c/summary\u003e\n\nRun directly without installing:\n\n```bash\nnix run github:juanibiapina/gob -- --help\n```\n\nOr install to your profile:\n\n```bash\nnix profile install github:juanibiapina/gob\n```\n\nOr add to your flake:\n\n```nix\n{\n  inputs = {\n    nixpkgs.url = \"github:NixOS/nixpkgs/nixpkgs-unstable\";\n    gob.url = \"github:juanibiapina/gob\";\n    # Optional: use your nixpkgs instead of gob's pinned version\n    # gob.inputs.nixpkgs.follows = \"nixpkgs\";\n  };\n\n  outputs = { self, nixpkgs, gob, ... }: {\n    # Use gob.packages.${system}.default\n  };\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ePre-built Binaries\u003c/summary\u003e\n\nDownload the latest release for your platform from the [Releases page](https://github.com/juanibiapina/gob/releases).\n\n**Available platforms**: Linux, macOS (both amd64 and arm64)\n\n```bash\n# Download the appropriate binary for your platform\n# For example, macOS Apple Silicon (arm64):\ncurl -LO https://github.com/juanibiapina/gob/releases/latest/download/gob_VERSION_darwin_arm64.tar.gz\n\n# Extract the archive\ntar -xzf gob_VERSION_darwin_arm64.tar.gz\n\n# Move to your PATH\nsudo mv gob /usr/local/bin/\n\n# Verify installation\ngob --version\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBuild from Source\u003c/summary\u003e\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions.\n\n\u003c/details\u003e\n\n## Quick Start\n\n```bash\n# Usage overview\ngob\n\n# Run a command and wait for completion\ngob run make test\n\n# Add a background job (returns immediately)\ngob add -- make test\ngob add -- pnpm --filter web typecheck\n\n# Wait for a job to complete\ngob await abc\n\n# List all jobs\ngob list\n\n# View stdout output\ngob stdout abc\n\n# Stop a job\ngob stop abc\n\n# Remove a stopped job\ngob remove abc\n```\n\n## Using with AI Coding Agents\n\nFor AI agents, add the following instructions to your agent's configuration file (`CLAUDE.md`, `AGENTS.md`, etc).\n\n````markdown\n## Background Jobs with `gob`\n\nUse `gob` for servers, long-running commands, and builds.\n\n### When to Use gob\n\nUse `gob` for:\n- **Servers**: `gob add npm run dev`\n- **Long-running processes**: `gob add npm run watch`\n- **Builds**: `gob run make build`\n- **Parallel build steps**: Run multiple builds concurrently\n\nDo NOT use `gob` for:\n- Quick commands: `git status`, `ls`, `cat`\n- CLI tools: `jira`, `kubectl`, `todoist`\n- File operations: `mv`, `cp`, `rm`\n\n### gob Commands\n\n- `gob add \u003ccmd\u003e` - Start command in background, returns job ID\n- `gob add --description \"context\" \u003ccmd\u003e` - Start with description for context\n- `gob run \u003ccmd\u003e` - Run and wait for completion (equivalent to `gob add` + `gob await`)\n- `gob run --description \"context\" \u003ccmd\u003e` - Run with description for context\n- `gob await \u003cjob_id\u003e` - Wait for job to finish, stream output\n- `gob await-any` - Wait for whichever job finishes first\n- `gob list` - List jobs with IDs, status, and descriptions\n- `gob stdout \u003cjob_id\u003e` - View current output (useful if job may be stuck)\n- `gob stop \u003cjob_id\u003e` - Graceful stop\n- `gob restart \u003cjob_id\u003e` - Stop + start\n\n### Stuck Detection\n\n`gob run` and `gob await` automatically detect potentially stuck jobs:\n- Timeout: avg duration + 1 min (or 5 min if no history), triggers if no output for 1 min\n- Job continues running in background\n- Use `gob stdout \u003cid\u003e` to check output, `gob await \u003cid\u003e` to continue waiting\n\n### Examples\n\nServers and long-running:\n```\ngob add npm run dev                              # Start dev server\ngob add --description \"File watcher\" npm run watch  # With description\n```\n\nBuilds:\n```\ngob run make build                           # Run build, wait for completion\ngob run npm run test                         # Run tests, wait for completion\ngob run --description \"Type check\" npm run typecheck  # With description\n```\n\nParallel builds:\n```\ngob add npm run lint\ngob add npm run typecheck\ngob await-any             # Wait for first to finish\ngob await-any             # Wait for second to finish\n```\n\nRegular commands (no gob):\n```\ngit status\nkubectl get pods\njira issue list\n```\n````\n\n## Interactive TUI\n\nLaunch a full-screen terminal interface for managing jobs:\n\n```bash\ngob tui\n```\n\n### Layout\n\nThe TUI has an info bar and five panels:\n\n- **Info bar**: Shows working directory and version\n- **Panel 1 (Jobs)**: List of all jobs with status (◉ running, ✓ success, ✗ failed)\n- **Description**: Shows job description (only visible when selected job has one)\n- **Panel 2 (Ports)**: Listening ports for the selected job\n- **Panel 3 (Runs)**: Run history for the selected job\n- **Panel 4 (stdout)**: Standard output of selected run\n- **Panel 5 (stderr)**: Standard error of selected run\n\n### Key Bindings\n\n| Key | Action |\n|-----|--------|\n| `↑/k`, `↓/j` | Navigate / scroll |\n| `h/l` | Scroll log horizontally (in log panels) |\n| `H/L` | Scroll log horizontally (from jobs/runs panels) |\n| `g/G` | Go to first/last |\n| `f` | Toggle follow mode |\n| `w` | Toggle line wrap |\n| `s/S` | Stop / kill job |\n| `r` | Restart job |\n| `d` | Delete stopped job/run |\n| `n` | New job |\n| `1/2/3/4/5` | Switch to panel |\n| `?` | Show all shortcuts |\n| `q` | Quit |\n\n### Auto-Start with Gobfile\n\nCreate a `.config/gobfile.toml` in your project directory to automatically start jobs when the TUI launches:\n\n```toml\n[[job]]\ncommand = \"npm run dev\"\ndescription = \"Frontend on http://localhost:3000. Check here for UI errors.\"\n\n[[job]]\ncommand = \"npm run api\"\ndescription = \"API server on http://localhost:4000. Check logs for request debugging.\"\n\n[[job]]\ncommand = \"npm run storybook\"\ndescription = \"Component library on http://localhost:6006\"\nautostart = false  # Add but don't start automatically\n\n[[job]]\ncommand = \"npm run db:reset\"\ndescription = \"DANGER: Drops and recreates the database\"\nblocked = true  # Prevent accidental execution\n```\n\n**Fields:**\n- `command` (required): The command to run\n- `description` (optional): Context for AI agents (ports, URLs, what to check for)\n- `autostart` (optional): Whether to start the job when TUI opens (default: `true`)\n- `blocked` (optional): If `true`, the job cannot be started; CLI shows description when attempted (default: `false`)\n\n**Behavior:**\n- Jobs are started asynchronously when TUI opens (if `autostart = true`)\n- Jobs are stopped when TUI exits (including when terminal is killed)\n- Already-running jobs have their descriptions updated if different\n- Stopped jobs with matching commands are restarted\n- Jobs with `autostart = false` are added but not started\n\n**Tip:** Add `.config/gobfile.toml` to `.gitignore` if you don't want to share it.\n\n## CLI Reference\n\nRun `gob \u003ccommand\u003e --help` for detailed usage, examples, and flags.\n\n| Command | Description |\n|---------|-------------|\n| `run \u003ccmd\u003e` | Run command and wait for completion (`--description` to add context) |\n| `add \u003ccmd\u003e` | Start background job (`--description` to add context) |\n| `await \u003cid\u003e` | Wait for job, stream output, show summary |\n| `await-any` | Wait for any job to complete (`--timeout`) |\n| `await-all` | Wait for all jobs to complete (`--timeout`) |\n| `list` | List jobs (`--all` for all directories) |\n| `runs \u003cid\u003e` | Show run history for a job |\n| `runs delete \u003crun_id\u003e` | Delete a stopped run and its logs |\n| `stats \u003cid\u003e` | Show statistics for a job |\n| `stdout \u003cid\u003e` | View stdout (`--follow` for real-time) |\n| `stderr \u003cid\u003e` | View stderr (`--follow` for real-time) |\n| `logs` | Follow all output for current directory |\n| `ports [id]` | List listening ports (`--all` for all jobs) |\n| `stop \u003cid\u003e` | Stop job (`--force` for SIGKILL) |\n| `start \u003cid\u003e` | Start stopped job |\n| `restart \u003cid\u003e` | Stop + start job |\n| `signal \u003cid\u003e \u003csig\u003e` | Send signal (HUP, USR1, etc.) |\n| `remove \u003cid\u003e` | Remove stopped job |\n| `shutdown` | Stop all running jobs, shutdown daemon |\n| `tui` | Launch interactive TUI |\n\n## Shell Completion\n\n`gob` supports shell completion for Bash, Zsh, and Fish. Completions include dynamic job ID suggestions with command descriptions.\n\n\u003cdetails\u003e\n\u003csummary\u003eBash\u003c/summary\u003e\n\n```bash\n# Add to ~/.bashrc\nsource \u003c(gob completion bash)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eZsh\u003c/summary\u003e\n\n```bash\n# Add to ~/.zshrc\nsource \u003c(gob completion zsh)\n```\n\nIf you get \"command not found: compdef\", add this before the source line:\n```bash\nautoload -Uz compinit \u0026\u0026 compinit\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eFish\u003c/summary\u003e\n\n```bash\n# Add to ~/.config/fish/config.fish\ngob completion fish | source\n```\n\n\u003c/details\u003e\n\n## Telemetry\n\n`gob` collects anonymous usage telemetry to help inform development priorities. Only usage metadata is collected; command arguments and output are never recorded.\n\nYou can opt out by setting `GOB_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1` in your environment.\n\nSee [docs/telemetry.md](docs/telemetry.md) for details on what's collected.\n\n## Contributing\n\nInterested in contributing? Check out [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing instructions, and contribution guidelines.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=juanibiapina/gob\u0026type=Date)](https://star-history.com/#juanibiapina/gob\u0026Date)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuanibiapina%2Fgob","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjuanibiapina%2Fgob","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuanibiapina%2Fgob/lists"}