ghost findReview the code you’re working on.
Run local Python checks and four focused JavaScript / TypeScript rules. Inspect findings alongside scope, file locations, and scanner evidence.
Offline static checks · Saved locallyLOCAL DEVELOPMENT AGENT
Security review.
In your terminal.
Ghost reviews your code, investigates failures, and tests proposed repairs in isolated worktrees. You decide what changes.
macOS & Linux / Python 3.12+
v0.1.0 Early access · MIT open source
+------------------------------------------------------------------------------+ | G H O S T v0.1.0 / LOCAL | | /tmp/ghost-gallery-cy9jh41w/demo-project Branch: main | +------------------------------------------------------------------------------+ +- START ----------------------------------------------------------------------+ | Start your first review | | scope | | Check which files Ghost can review, then run find. | +------------------------------------------------------------------------------+ Review: scope / find / brief Guided scan and repair: review While coding: watch / run <command> Local access: auth --init / commands / Tab options / help <command> / home return
+------------------------------------------------------------------------------+ | G H O S T v0.1.0 / LOCAL | | /tmp/ghost-gallery-cy9jh41w/demo-project Branch: main | +------------------------------------------------------------------------------+ +- START ----------------------------------------------------------------------+ | Start your first review | | scope | | Check which files Ghost can review, then run find. | +------------------------------------------------------------------------------+ Review: scope / find / brief Guided scan and repair: review While coding: watch / run <command> Local access: auth --init / commands / Tab options / help <command> / home return
The current REPL welcome screen. Watching is opt-in.
+- Ghost / Security brief -----------------------------------------------------+ | SAVED REVIEW | | Saved snapshot / current source was not rechecked | | Audit: e062eece014b4ca6970dd09a65221023 | | Started: 2026-10-14T10:27:09.049119+00:00 | | Base commit: 5224ab41ee99 | | Scanner: Ghost / Bandit + Semgrep | | | | 3 source files / 2 static candidates | | HIGH: 0 / MEDIUM: 2 / LOW: 0 / UNDEFINED: 0 | +------------------------------------------------------------------------------+ Scope: Python: Bandit default rules. JavaScript/TypeScript: four bundled rules. Static candidates only. Scan confinement recorded: yes Excluded: 0 / Other-language files: 0 Priority: severity, then static confidence. Confidence does not establish exploitability. Local access: not run Review first Priority Candidate / location Rule / confidence / ID MEDIUM / SUSPECTED Dynamic expression evaluation B307 / HIGH parser.py:2 f4a67e05588b5e6daa9d MEDIUM / SUSPECTED Dynamic expression evaluation GJS001 / MEDIUM client.ts:1 ab070eda1c9eb2f5bb9e Showing 2 of 2 static candidates / 1 diagnostic notes saved Next steps ghost findings --audit e062eece014b4ca6970dd09a65221023 --id f4a67e05588b5e6daa9d ghost findings --audit e062eece014b4ca6970dd09a65221023 ghost find Guided scan, brief and repair: ghost review Static candidates are suspected; local access proof covers configured cases only. This summary is not deployment approval. Read the full saved review for evidence. Share this review: ghost brief --audit e062eece014b4ca6970dd09a65221023 --limit 5 --markdown
+- Ghost / Security brief -----------------------------------------------------+ | SAVED REVIEW | | Saved snapshot / current source was not rechecked | | Audit: e062eece014b4ca6970dd09a65221023 | | Started: 2026-10-14T10:27:09.049119+00:00 | | Base commit: 5224ab41ee99 | | Scanner: Ghost / Bandit + Semgrep | | | | 3 source files / 2 static candidates | | HIGH: 0 / MEDIUM: 2 / LOW: 0 / UNDEFINED: 0 | +------------------------------------------------------------------------------+ Scope: Python: Bandit default rules. JavaScript/TypeScript: four bundled rules. Static candidates only. Scan confinement recorded: yes Excluded: 0 / Other-language files: 0 Priority: severity, then static confidence. Confidence does not establish exploitability. Local access: not run Review first Priority Candidate / location Rule / confidence / ID MEDIUM / SUSPECTED Dynamic expression evaluation B307 / HIGH parser.py:2 f4a67e05588b5e6daa9d MEDIUM / SUSPECTED Dynamic expression evaluation GJS001 / MEDIUM client.ts:1 ab070eda1c9eb2f5bb9e Showing 2 of 2 static candidates / 1 diagnostic notes saved Next steps ghost findings --audit e062eece014b4ca6970dd09a65221023 --id f4a67e05588b5e6daa9d ghost findings --audit e062eece014b4ca6970dd09a65221023 ghost find Guided scan, brief and repair: ghost review Static candidates are suspected; local access proof covers configured cases only. This summary is not deployment approval. Read the full saved review for evidence. Share this review: ghost brief --audit e062eece014b4ca6970dd09a65221023 --limit 5 --markdown
Executed Python / TypeScript sample. Static findings remain suspected.
╭──────────────────────────────────────────────────────────────────────────────╮ │ SECURITY REPAIR / VERIFIED │ │ Solution: 4e83d476c9be4ee992a7e7656661927e │ │ Finding: f4a67e05588b5e6daa9d │ ╰──────────────────────────────────────────────────────────────────────────────╯ Runner: python_unittest / version 3.12.14 Selected tests: python -m unittest discover -v Executed tests: /workspace/ghost/.venv/bin/python -m unittest discover -v baseline project tests: exit 0 / 0.31s / 3 tests passed python_unittest / evidence complete Failed 0 / skipped 0 / cancelled 0 / TODO 0 Passing counts only; individual cases and assertion coverage are not measured. original security probe: exit 0 / 1.30s Function call executed; 3 literal cases preserved: True patched security probe: exit 0 / 1.29s Function call rejected; 3 literal cases preserved: True patched project tests: exit 0 / 0.26s / 3 tests passed python_unittest / evidence complete Failed 0 / skipped 0 / cancelled 0 / TODO 0 Passing counts only; individual cases and assertion coverage are not measured. Python rescan: completed Target scanner rule absent: yes --- parser.py +++ parser.py @@ -1 +1,2 @@ - return eval(value) + from ast import literal_eval as _ghost_literal_eval + return _ghost_literal_eval(value) Helper-level proof: function-call evaluation reproduced, then rejected; three literal cases preserved. Application reachability is not established. This repair intentionally rejects expressions. Review whether the function is intended to parse literals. Project tests are trusted code; their coverage is not a security guarantee.
╭──────────────────────────────────────────────────────────────────────────────╮ │ SECURITY REPAIR / VERIFIED │ │ Solution: 4e83d476c9be4ee992a7e7656661927e │ │ Finding: f4a67e05588b5e6daa9d │ ╰──────────────────────────────────────────────────────────────────────────────╯ Runner: python_unittest / version 3.12.14 Selected tests: python -m unittest discover -v Executed tests: /workspace/ghost/.venv/bin/python -m unittest discover -v baseline project tests: exit 0 / 0.31s / 3 tests passed python_unittest / evidence complete Failed 0 / skipped 0 / cancelled 0 / TODO 0 Passing counts only; individual cases and assertion coverage are not measured. original security probe: exit 0 / 1.30s Function call executed; 3 literal cases preserved: True patched security probe: exit 0 / 1.29s Function call rejected; 3 literal cases preserved: True patched project tests: exit 0 / 0.26s / 3 tests passed python_unittest / evidence complete Failed 0 / skipped 0 / cancelled 0 / TODO 0 Passing counts only; individual cases and assertion coverage are not measured. Python rescan: completed Target scanner rule absent: yes --- parser.py +++ parser.py @@ -1 +1,2 @@ - return eval(value) + from ast import literal_eval as _ghost_literal_eval + return _ghost_literal_eval(value) Helper-level proof: function-call evaluation reproduced, then rejected; three literal cases preserved. Application reachability is not established. This repair intentionally rejects expressions. Review whether the function is intended to parse literals. Project tests are trusted code; their coverage is not a security guarantee.
Verified Python helper recipe. Three project tests passed; patch unapplied.
Python + JavaScript / TypeScriptLocal by defaultAI connection optionalSource changes need approval
THE WORKFLOW
A review you can act on.
Start with your repository. Keep the findings, evidence, and proposed change in the same workflow.
- 01 / SCAN
Know what was checked.
Inspect the source scope, run local checks, and see incomplete coverage with the findings.
$ ghost find - 02 / INVESTIGATE
Read the evidence.
Open a finding, trace its inputs, or read a saved brief. A pattern match is a starting point.
$ ghost brief - 03 / TEST & APPROVE
Inspect a proposed repair.
For supported repairs, run your selected tests in isolation. Review the patch before applying it.
$ ghost solve <id> --tests …
YOUR LOCAL WORKSPACE
From finding
to tested change.
Use commands directly or work with Ghost in the REPL. Connect your own AI provider when you want advice or a tested proposal.
Supported workflowsghost solve <id> --tests …Test the change before it reaches your repo.
Ghost tests a supported Python recipe or an optional AI proposal in a disposable Git worktree. Review the diff and test results before approving application.
Isolated experiments · Approval requiredghost run / ghost debugKeep the context behind a failure.
Record the commands you choose to run, watch edits when you ask, and investigate failures with their saved output and session history.
Explicit capture · Revisit the evidence
Your project stays yours.
Default reviews run offline and save evidence in .ghost/. AI source sharing is opt-in. Ghost shows the proposed diff and asks before applying a change.
GET STARTED
Install. Open your repo. Review.
uv tool install --python 3.12 git+https://github.com/Devesh36/ghost.git && uv tool update-shellRequires uv, Git, and your OS sandbox. Open a new terminal if PATH was updated.
brew tap devesh36/ghost https://github.com/Devesh36/ghost.git && brew install --HEAD devesh36/ghost/ghostInstalls Git, Python 3.12, uv, and Linux Bubblewrap through the Ghost tap.
curl -fsSL https://raw.githubusercontent.com/Devesh36/ghost/main/install.sh | bashUses an existing Homebrew or uv installation. Inspect the installer before running it.
Then, inside your Git project:
ghost doctor → ghost replDevelopment version from main. Python 3.12+, a committed Git repository, and macOS sandbox-exec or Linux Bubblewrap. Default scans run offline after installation.
BUILDING GHOST
Development phases.
Follow the build, from the first debugger to today’s local agent. Open a phase for its commits and dated development notes.
93 recorded commitsSince October 2026Dates in India Standard Time
The local debugging foundationFrom an idea to a working CLI and REPL: record commands, inspect failures, and test changes in isolated experiments.13 commits
Documented the original local debugging idea and intended workflow.
first commitImplemented the first CLI, file and command collectors, local database, investigation agents, and isolated experiments.
cookingBuild Ghost debugging MVP with REPL, guided demo, and docs
Harden investigation execution and add environment diagnostics
Bound model transport deadlines and payloads with adversarial coverage
Add responsive session browser and historical inspection commands
Install single-file patches atomically and preserve source formatting
Add investigation history and fix saved report ordering
Prevent overlapping investigations with checkout-scoped OS locking
Block recognized credentials at model evidence boundaries
refactor: adopt OpenSRE-style layered package layout
feat: retry recorded failures from CLI and REPL
feat: add confined offline security audits and saved findings
Security becomes the daily workflowOffline findings, a bounded Python repair recipe, and configured cross-user access checks turn debugging into a security review workflow.4 commits
A terminal you can live inSource scope, conversational actions, provider connections, slash commands, and saved themes make the local workflow easier to navigate.15 commits
fix: require protected-content evidence for access checks
feat: add safe authorization contract preflight
fix: detect order-sensitive authorization evidence
feat: add source scope browser
fix: escape and bound live command output
fix: render watcher and history metadata literally
fix: block Git helper execution in agent reads
feat: add conversational Ghost with multi-provider connections
feat: refresh Ghost branding and terminal typography
feat: guide Ghost users through daily security workflows
feat: add slash command picker to Ghost REPL
feat: add provider picker and Claude Code login support
feat: add live terminal themes with previews and saved preferences
docs: explain using Ghost in a specific repository
Enforce agent model deadlines without abandoning sandbox cleanup
Evidence you can come back toSaved review history, stricter verification, private persistence, and diagnostics keep evidence inspectable and protect the source being reviewed.9 commits
Add security review history and saved audit inspection
docs: add real Ghost terminal screenshots to README
Reject incomplete debugger evidence and patch verification
Add MIT license and distribution license metadata
Document source provenance audit and prohibit Apache code imports
Reject security repairs when verification changes the reviewed snapshot
Protect private persistence paths and close SQLite transactions
Improve doctor with read-only storage checks and strict diagnostics
Add focused finding chat and bounded audit metadata
Preparing an early-access releaseReview comparisons, sandbox inventory, and Linux/macOS qualification support a gated draft release with explicit limits.12 commits
Protect watcher reads and clarify file observation scope
Add evidence-conscious security review comparison command
Record scanner configuration fingerprints and guard review comparisons
Add gated draft release workflow and distribution validation
Add isolated scanner diagnostics for hosted release checks
Expose bounded diagnostics for the synthetic scanner probe
Fix release qualification with fresh Python caches and robust help assertions
Keep inherited XDG configuration inside experiment sandboxes
Record successful Linux and macOS release qualification [skip ci]
Add safe sandbox inventory and polish project launch page
Document v0.1.0 early access draft
Correct release qualification status in readiness notes
Make a review easier to act onLocked dependencies and saved security briefs bring repeatable development, responsive review summaries, and practical guides.2 commits
Guided reviews and tested changesInstallation, the Next.js website, grouped comparisons, transactional history upgrades, optional AI review, and explicit JavaScript test evidence connect the workflow.18 commits
Improve review triage and add one-command Ghost installation
Add Ghost landing page and manual Pages deployment
Add GitHub Actions workflow for Jekyll deployment
Migrate Ghost landing page to Next.js for Vercel deployment
Add grouped and filtered saved review comparisons
Separate debugger orchestration from terminal reporting
Merge pull request #21 from Devesh36/refactor/investigation-reporting
Match the exact domain namespace in architecture checks
Version local history and make database upgrades transactional
Merge pull request #23 from Devesh36/feat/transactional-database-upgrades
Add guided security review with optional LLM assistance
Clarify verified recipe limits in demo documentation
Gate JavaScript repairs on explicit Node test evidence
Add bounded chat workflows and tested requested changes
Make chat expiry regression independent of runner uptime
Merge pull request #25 from Devesh36/feat/guided-ai-security-review
Merge pull request #22 from Devesh36/refactor/investigation-reporting
Merge pull request #19 from Devesh36/feat/review-comparison-triage
Open the workflow to everyoneIn-site docs, a consistent terminal gallery, and this development log explain how to use Ghost and how it is evolving.6 commits · 5 development notes
From development conversations
A repeatable cloud development environment
Installed locked Python and website dependencies, checked the real scanner and repair demo, validated website builds and pages, and added a child-process reaper for the container’s cancellation tests. This prepares development; it does not add an application feature.
A clearer guide and a visible development story
Organized the docs around setup, review, and repair; refreshed terminal captures with one Ghost theme; and added this dated phase timeline with an expandable record of every available commit. Development notes preserve the outcome of this conversation.
A calmer, more readable landing page
Refined the hero and section spacing, increased supporting text sizes, organized workflow and coverage into consistent cards, and moved installation to the final call to action. Compact expandable phases keep the complete dated commit record accessible on desktop, mobile, and without JavaScript.
A more helpful interactive workspace
Organized the REPL welcome screen, added a responsive command-description footer, and extended the picker to local command options, finite choices, workflow guides, and command help. Selections edit the input before a separate submission; shared execution guards and plain-terminal fallbacks remain in place. Updated the guide and workspace capture to show the current interface.
One Ghost identity, from terminal to website
Rebuilt the landing page around the product, its review workflow, and actual workspace, review, and repair output. Website colors now come directly from the terminal palette. Matching typography, documentation, and six refreshed captures give Ghost one consistent identity; responsive captures keep the product readable on mobile.
Add in-site usage documentation and terminal gallery
Make documentation prominent on the landing page
Organize docs, refresh terminal gallery, and add development phases
Refine landing layout and make development phases easier to browse
Improve REPL workspace and contextual command completion
Align product website with Ghost terminal identity
Improve review accuracyExplicit source freshness, broader Node shell detection, and independent positive and negative fixtures make saved reviews more useful and keep future detection changes measurable.2 commits · 1 development notes
From development conversations
Current source checks and broader shell review coverage
Added ghost freshness to inspect saved source hashes, moved HEAD, and unreviewed supported paths without rescanning or changing evidence. Expanded Node shell-command detection across imports, aliases, synchronous APIs, and explicit shell options. On 179 independent fixtures, detection rose from 3 to 115 expected candidates, with no matches in 64 safe or unrelated cases. Linux regressions and the real review/repair journey passed. Static candidates remain suspected; the regression corpus becomes part of future improvement checks.
Improve security review freshness and Node shell detection
Record completed accuracy cycle in development history
Follow changes with their evidencePaged review history and comparison filters make larger reviews navigable. Saved source identity, baseline access context, and more accurate duplicate pairing keep changes connected to their evidence.2 commits · 1 development notes
From development conversations
Browse changes while keeping the evidence visible
Added category, severity and confidence filters and paged comparisons, plus review history pages with full totals from one read-only snapshot. Repeated locations show saved source changes; both review contexts and baseline access counts remain visible even when comparison is blocked. Equal-level duplicate pairing avoids misleading severity changes when a duplicate disappears. Real stale-source, rescan and comparison captures extend the consistent terminal gallery. The next cycle prioritizes the observed storage-concurrency issue before adding reviewer decisions.
Improve review comparison accuracy and history navigation
Record completed review navigation cycle in phase history
Graph context for security triageA new FalkorDB demo ranks synthetic findings through package, service, internet exposure, ownership, and incident relationships, then explains the graph paths behind its first priority.6 commits · 3 development notes
From development conversations
FalkorDB triage for Graph Hacks
Built a new optional graph triage command, synthetic dataset, parameterized loader, Cypher ranking and evidence-path agent for the Graph Hacks submission. The real FalkorDB demo prioritizes F-002 through its public-service and open-incident links; removing the incident edge changes the recommendation. Existing Ghost findings, audits and repairs remain separate. The guide records the schema, local setup and exact boundary between new event work and reused Ghost foundations.
A reproducible Graph Hacks submission demo
Added a disposable FalkorDB walkthrough that changes one incident edge and verifies F-002 → F-003 → F-002, plus regression checks, CI replay, a captioned video and a submission brief. Recorded the new-versus-reused boundary and pending eligibility checks explicitly: the live event rules remain blocked by the environment network policy, so registration, build-window compliance and submission are not claimed.
Explain changing SQLite sidecars without weakening storage checks
Added a distinct recovery message for repeated safe sidecar replacement and bounded diagnostic notes for storage guards. Deterministic races cover retries, unsafe replacements, real SQLite sidecar removal and descriptor cleanup. A concurrent stress run completed 3,600 writes and 3,600 reads; the earlier cancellation failure remains unexplained. Recorded a ten-minute development checkpoint procedure; no unattended agent scheduler is installed.
Add FalkorDB graph triage demo for Graph Hacks
Record Graph Hacks implementation in development history
Prepare reproducible Graph Hacks submission evidence
Record Graph Hacks submission preparation in phase history
Distinguish unstable SQLite sidecars from unsafe storage
Record the storage reliability development cycle
The next phaseContinuing improvements to Ghost, recorded as new commits and development notes arrive.4 commits · 2 development notes
From development conversations
One command to record the FalkorDB demo
Added ghost demo --graph with live ranking, incident-link removal and restoration in a temporary graph. Interactive Enter-key pauses support recording; JSON and no-pause modes support automation. The installed command works outside the checkout, preserves existing demo modes and graphs, and cleans up on interruption or partial-load failure.
Record the graph demo without Docker
Added an optional FalkorDBLite runtime for ghost demo --graph --embedded. Ghost owns a native database process on a private Unix socket, executes the same live ranking and evidence queries, and stops the process and removes temporary data on success or interruption. The default server flow remains available; native platform requirements and dependency licenses are documented.
Add one-command live FalkorDB recording demo
Record the one-command graph demo in the phase timeline
Run the FalkorDB demo natively without Docker
Record the native graph demo in the phase timeline
Commit records come from the repository. Development notes summarize completed work. All dates use India Standard Time.
Do I need an AI subscription?
No. Static reviews, saved findings, briefs, and the supported Python repair recipe work without a model or API key. AI assistance uses the provider you choose, including local Ollama.
What can Ghost repair today?
The deterministic recipe covers a constrained Python eval-to-literal-parser pattern. Optional AI proposals support one Python or plain JavaScript file with explicitly selected tests. TypeScript, Jest, and Vitest repairs are unsupported. AI proposals are tested, not security-verified.
Does my code leave my machine?
Default static scans run locally. Optional AI reviews and proposals share the selected source or context with your configured provider, with your consent. Reviews and command history are stored in your project’s .ghost directory.
What does a clean scan mean?
The scoped checks completed without reported findings. Ghost has bounded coverage; a clean scan does not certify your application secure. Use it alongside project tests and human review.