DEV Community: Niranjan R Soorej

# 👻 Phantom-Shell — The Haunted Terminal

Niranjan R Soorej — Fri, 30 Oct 2026 20:21:29 +0000

👻 Phantom-Shell — The Haunted Terminal

Your terminal remembers what went wrong. Your AI investigates why.

What if your terminal could remember its failures, investigate the evidence, and help you understand problems that would otherwise disappear into a sea of logs?

Phantom-Shell is an open-source, local-first AI terminal investigator designed to turn mysterious command-line failures into structured, evidence-backed investigations. Instead of treating every error as an isolated event, it captures execution history, connects related incidents, investigates problems with local AI, and aims to preserve verified knowledge for future sessions.

The goal is simple: make debugging less like guessing and more like detective work.

What I Built

🕵️ A terminal that investigates its own failures

Developers spend a surprising amount of time reconstructing what happened before a failure. Which command caused it? Was the same issue encountered before? Does the configuration actually support the proposed explanation?

Phantom-Shell explores a different approach: turn terminal activity into a persistent investigation trail.

Here's what the project includes:

Terminal event capture: Records command execution information, output, exit codes, and working-directory context.
Persistent local storage: Uses SQLite to preserve events and investigation state.
Local AI investigation: Integrates with Ollama to investigate incidents using locally hosted language models.
Evidence validation: Includes components intended to distinguish supported conclusions from assumptions.
Read-only investigation tools: Allows the investigator to inspect project information through constrained tools.
Human-controlled actions: Provides an approval workflow for proposed actions rather than giving AI unrestricted control.
Investigation dashboard: Offers a local web interface for reviewing investigation activity.
Incident memory: Implements memory management intended to preserve and reuse verified knowledge.

👻 How it fits the theme

The ghost in the machine is the history of a failure that developers can no longer remember.

A build breaks. A test fails. A configuration behaves unexpectedly. The clues are scattered across commands, output, and project files.

Phantom-Shell gives those clues a persistent place to live and uses AI to help investigate them.

Rather than presenting AI as an infallible oracle, the project explores how local models, structured evidence, controlled tools, and persistent memory can work together to make AI-assisted debugging more transparent.

Demo

Dashboard: http://127.0.0.1:8765/ when running locally.

The dashboard is intended for local access; it is not a publicly hosted deployment.

The basic capture workflow has been demonstrated:

phantomshell run --no-model -- bash -lc 'echo "PhantomShell capture works"'
phantomshell report

The first command executes a command through Phantom-Shell, and the second displays the captured event and output.

For the current implementation, interactive shell capture and some end-to-end investigation scenarios are still being verified.

Phantom-Shell in Action 👻

The Phantom-Shell dashboard brings terminal activity into a single investigation timeline. Each captured command is displayed alongside its exit code and output, making successful executions and failures easier to trace.

In this example, the timeline shows a successful build alongside a configuration-related failure caused by a missing src/app.py entry point. Rather than losing the error in terminal scrollback, Phantom-Shell preserves it as part of the project's execution history.

The dashboard runs locally, with the displayed status indicating that inference uses Ollama through a loopback connection rather than external model API calls.

The idea: preserve the evidence, reconstruct the failure, and make debugging more systematic.

Code

GitHub repository: NiranjanRSoorej06/Phantom-Shell

The project is organized into separate components for terminal capture, event persistence, investigation, evidence handling, memory, policy enforcement, and the local dashboard.

The modular structure is intended to make it easier for contributors to improve individual capabilities without having to rebuild the entire application.

How I Built It

Phantom-Shell is implemented in Python, with local persistence, model integration, and a lightweight web dashboard.

Core technologies:

Python: CLI, event processing, orchestration, and investigation logic.
Ollama: Local inference through a locally hosted language model.
SQLite: Persistent storage for terminal events and investigation state.
FastAPI: Dashboard and API layer.
Uvicorn: Local web server.
Pytest: Automated testing.

The architecture

The application separates its responsibilities into several layers:

Capture: Collect command execution information and output.
Storage: Persist structured events and investigation data in SQLite.
Episode management: Associate related events with recurring incidents.
Investigation: Use available evidence and local AI to analyze an incident.
Evidence and policy: Apply checks and restrictions to investigation outputs and proposed actions.
Memory: Manage incident knowledge and its verification status.
Dashboard: Provide a local interface for reviewing investigation activity and proposed actions.

One important design decision was to separate AI reasoning from action execution. Generating a plausible fix is not the same as proving that it is correct, and proposing an action should not automatically authorize it.

Testing and current status

The existing automated test suite passes 25 tests in 0.82 seconds. Basic one-shot command capture and event reporting have also been demonstrated.

However, passing unit tests is not the same as proving every end-to-end workflow. Interactive shell capture, cross-session memory promotion, network-isolated operation, clean-clone setup, and live-model investigation quality remain areas for further verification.

Why Does Open Innovation Matter?

An AI terminal investigator operates close to a developer's source code, command history, configuration, and debugging workflow. That makes transparency and control especially important.

Open innovation makes it possible to inspect the implementation, experiment with different models, improve the investigation pipeline, and contribute tools without depending on a single proprietary provider.

Using Ollama also allows the application to work with locally hosted models rather than requiring every investigation to be sent to a remote AI API. Actual offline operation still depends on the model and its dependencies being available locally, and is a scenario that needs dedicated verification.

An open-source implementation also makes the safety boundaries inspectable. Developers can review how events are stored, how tools are constrained, how proposed actions are handled, and how evidence is used.

I want Phantom-Shell to be something developers can question, modify, test, and improve — not a black box they have to trust.

My Agent Session

Phantom-Shell itself is the project built for this challenge. Its development involved working through implementation details, testing capture behavior, examining failures, and identifying remaining integration gaps.

Phantom-Shell — The Haunted Terminal

You

<environment_context>
<cwd>[PROJECT_PATH]/E8BA8138BA810472/My Folders/Hacktoberfest/Phantom-Shell</cwd>
<shell>bash</shell>
<current_date>2026-10-30</current_date>
<timezone>Asia/Kolkata</timezone>
<filesystem><workspace_roots><root>[PROJECT_PATH]/E8BA8138BA810472/My Folders/Hacktoberfest/Phantom-Shell</root></workspace_roots><permission_profile type="managed"><file_system type="restricted"><entry access="read"><special>:root</special></entry><entry access="write"><path>[PROJECT_PATH]/E8BA8138BA810472/My Folders/Hacktoberfest/Phantom-Shell</path></entry><entry access="write"><special>:slash_tmp</special></entry><entry access="write"><special>:tmpdir</special></entry><entry access="read"><path>[PROJECT_PATH]/E8BA8138BA810472/My Folders/Hacktoberfest/Phantom-Shell/.git</path></entry><entry access="read"><path>[PROJECT_PATH]/E8BA8138BA810472/My Folders/Hacktoberfest/Phantom-Shell/.agents</path></entry><entry access="read"><path>[PROJECT_PATH]/E8BA8138BA810472/My Folders/Hacktoberfest/Phantom-Shell/.codex</path></entry><entry access="read"><path>[PROJECT_PATH]/E8BA8138BA810472/My Folders/Hacktoberfest/Phantom-Shell/.aws</path></entry></file_system></permission_profile></filesystem>
</environment_context>

You

implement the plan.md

Agent

I’ll read plan.md and the repository guidance first, then implement its steps in the workspace.

Agent

The plan is a large staged build, and it explicitly requires acceptance checks and a PROGRESS.md entry after each task. I’m checking the current repo state and environment now so I can start at T0 and follow the plan’s gates in order.

Agent

The repo currently contains only plan.md. Python, Git, ripgrep, and Bash meet the stated version checks; the machine reports 9.1 GiB available RAM and no nvidia-smi. Ollama is installed, but its daemon is unavailable in the sandbox, so the required local Gemma probe is the T0 gate. I’m requesting permission to start Ollama and check whether the model is available; implementation beyond T0 depends on that gate.

Agent

The existing Ollama daemon is running outside the sandbox, and the Gemma 4 E4B download is progressing (about 93% at the last update). The plan’s local-model gate looks achievable; once the structured-output probe works, I’ll move into the first implementation tasks.

Agent

Gemma 4 E4B passed the local schema probe with {"ok": true} in about 20.5 seconds, including initial model load. I’m recording T0 and scaffolding the new Python project; then I’ll build the vertical slice task by task, keeping the implementation and evidence in PROGRESS.md. I’m also applying the repository’s community-wisdom workflow for non-trivial builds.

Agent

The T0 project files are in place, but the workspace marks .git read-only, so the plan’s required commit could not be created. I’ll record that limitation and continue with the source changes and acceptance commands; I can’t change Git history from this workspace.

Agent

The ingest and marker unit checks pass, and the one-command fallback emits the expected event schema for both false and echo hi. The interactive PTY path is not yet verified: it stalls under the available pseudo-terminal wrapper, and the default database location is outside the writable workspace. I’m recording those limits and continuing with the deterministic episode, investigation, and local dashboard pieces.

Agent

The deterministic episode tests pass. I’ve added the loopback dashboard and its token/Origin checks, but its TestClient acceptance check is hanging in this environment, so I’m not treating G1 as passed. Next I’m implementing the model schema contract, quote verifier, and backend-controlled tool policy so the main investigation path exists even while capture and dashboard integration need more work.

Agent

The model client is implemented with a strict loopback URL check, JSON schemas, one retry, and run logging. The sandbox blocks its HTTP request even though the earlier escalated curl probe worked, so I’m requesting approval to run the T5 acceptance call against the local Ollama daemon.

Agent

▸ wait {"cell_id":"59","yield_time_ms":30000,"max_tokens":1000}

Input

{
  "cell_id": "59",
  "yield_time_ms": 30000,
  "max_tokens": 1000
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"1beec5\",\"wall_time_seconds\":1.00106691,\"session_id\":15512,\"original_token_count\":0,\"output\":\"\"}"
  }
]

Agent

The core investigation path now includes per-session episode grouping, model-generated read-only check proposals, per-action approval endpoints, a deterministic evidence verifier, and watched-file memory. The earlier dashboard test stall came from this environment’s Starlette TestClient; I replaced it with HTTPX’s ASGI transport, and all 16 focused unit/security tests now pass. I’m checking whether the interactive capture path can be exercised with a purpose-built PTY harness.

Agent

▸ wait {"cell_id":"105","yield_time_ms":30000,"max_tokens":1000}

Input

{
  "cell_id": "105",
  "yield_time_ms": 30000,
  "max_tokens": 1000
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"e7438b\",\"wall_time_seconds\":1.001793075,\"session_id\":16429,\"original_token_count\":0,\"output\":\"\"}"
  }
]

Agent

▸ wait {"cell_id":"109","yield_time_ms":30000,"max_tokens":300}

Input

{
  "cell_id": "109",
  "yield_time_ms": 30000,
  "max_tokens": 300
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"c9803a\",\"wall_time_seconds\":1.001678649,\"session_id\":48271,\"original_token_count\":0,\"output\":\"\"}"
  }
]

Agent

The PTY harness confirms that the real wrapped Bash captured echo hi with exit 0 and false with exit 1, hid the OSC markers, propagated Ctrl-C as exit 130, and forwarded a 40×100 terminal resize to stty size. I’m turning that manual check into a repeatable smoke script, then I’ll finish the docs and re-run the full project checks.

Agent

The repeatable PTY smoke now passes, including Ctrl-C and resize; the focused suite passes 20 tests, and ruff check is clean. The local Gemma call also produced a valid, tool-specific inspect_project_tree proposal from the actual captured fixture failure. I’m reconciling the claims ledger and platform/license documentation next; the full two-session offline demo remains unverified.

Agent

The stricter tool-specific schema now yields a valid inspect_project_tree proposal (depth: 2) for the captured fixture failure; the last logged Plan run took 33.3 seconds and passed schema validation. To verify T8’s actual Conclude path, I’m requesting permission to run that proposed read-only tree check against the fixture and pass its evidence to local Gemma.

Agent

▸ wait {"cell_id":"145","yield_time_ms":30000,"max_tokens":1000}

Input

{
  "cell_id": "145",
  "yield_time_ms": 30000,
  "max_tokens": 1000
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"8ce5ec\",\"wall_time_seconds\":1.000435465,\"session_id\":78453,\"original_token_count\":0,\"output\":\"\"}"
  }
]

Agent

▸ wait {"cell_id":"151","yield_time_ms":30000,"max_tokens":2000}

Input

{
  "cell_id": "151",
  "yield_time_ms": 30000,
  "max_tokens": 2000
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.2 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"content\":[{\"type\":\"text\",\"text\":\"{\\\"Ok\\\":{\\\"id\\\":82,\\\"title\\\":\\\"Hacktoberfest Open-Source AI Challenge: Week 4\\\",\\\"slug\\\":\\\"hacktoberfest-week4-2026-10-26\\\",\\\"description\\\":\\\"The Hacktoberfest Open-Source AI Challenge: Week 4 runs October 26 to October 31. Build something spooky, or something that honors the past in the spirit of Día de los Muertos, with open-weight models or open-source AI. $2,850 in prizes across 21 winners.\\\\r\\\\n\\\\r\\\\nThis is the final challenge of our Hacktoberfest series. This year's Hacktoberfest is all about building brand-new projects with open-source AI and open-weight models, and the theme is intentionally broad, so interpret it however you'd like!\\\",\\\"details\\\":null,\\\"full_details\\\":\\\"The Hacktoberfest Open-Source AI Challenge: Week 4 runs October 26 to October 31. Build something spooky, or something that honors the past in the spirit of Día de los Muertos, with open-weight models or open-source AI. $2,850 in prizes across 21 winners.\\\\r\\\\n\\\\r\\\\nThis is the final challenge of our Hacktoberfest series. This year's Hacktoberfest is all about building brand-new projects with open-source AI and open-weight models, and the theme is intentionally broad, so interpret it however you'd like!\\\\r\\\\n\\\\r\\\\nOur Theme: Ghost in the Machine\\\\r\\\\n\\\\r\\\\nBuild something spooky, or something that honors the past in the spirit of Día de los Muertos, with open-weight models or open-source AI.\\\\r\\\\n\\\\r\\\\nThis week brings us Halloween on October 31 and Día de los Muertos on November 1 and 2, a stretch of the calendar when the line between past and present feels a little thinner. Whether that brings to mind things that go bump in the night, ofrendas glowing with marigolds and candlelight, or the memories and stories we carry with us, we want to see what it inspires you to build.\\\\r\\\\n\\\\r\\\\nThat can mean running an open-weight model, building on an open-source agent harness or framework, running inference locally, or all three. Whatever you pick, the open pieces should be what makes your project work.\\\\r\\\\n\\\\r\\\\nA few ideas to get you going:\\\\r\\\\n\\\\r\\\\n    A haunted terminal that \\\\\\\"possesses\\\\\\\" your shell and whispers back eerie commentary on the commands you run\\\\r\\\\n    A digital ofrenda builder that helps you write a remembrance for a loved one and gather their favorite foods, songs, and stories\\\\r\\\\n    An offline séance chatbot that channels the spirit of a long-dead programming language\\\\r\\\\n    A local oral history tool that records and transcribes family stories so they're never lost\\\\r\\\\n    A ghost story generator that weaves your smart home's sensor logs into a creepy tale of what happened while you were asleep\\\\r\\\\n    A project that brings an abandoned open-source tool or a forgotten corner of internet history back to life\\\\r\\\\n\\\\r\\\\nIn your post, tell us why open innovation matters for what you built. Does running your own model mean your project works with the lights (and the internet) off? Keep your family's photos and stories private and on your own machine? Make sure what you build isn't locked inside a service that might disappear someday? Tell us where your open-based approach worked better than a closed one.\\\\r\\\\n\\\\r\\\\nPrize Categories\\\\r\\\\n\\\\r\\\\nAlongside our overall winner, we have 20 prize categories for projects that use a specific partner's technology. You don't need to use any of these to win the overall prize. Full descriptions are on the HF26 DEV Challenge Hub (https://dev.to/challenges/hf26).\\\\r\\\\n\\\\r\\\\nFeatured categories: Best Use of Render, Best Use of TabPFN, Best Use of Tinker, Best Use of Arduino, Best Use of DigitalOcean, Best Use of Gemma\\\\r\\\\n\\\\r\\\\nPartner categories: Best Use of Auth0 for AI Agents, Best Use of Backboard, Best Use of Browserbase, Best Use of ElevenLabs, Best Use of Entire, Best Use of GitHub Copilot, Best Use of Mastra, Best Use of MongoDB Atlas, Best Use of Sentry Agent Tracing, Best Use of SerpApi, Best Use of Temporal, Best Use of Tiger Data, Best Use of Ultramarine (Paper Instruments), Best Use of a .tech Domain\\\\r\\\\n\\\\r\\\\nOne project can enter every category it genuinely uses, but you can only win once per challenge. Several partners are giving participants free credits and promo codes at hacktoberfest.com/my.\\\\r\\\\n\\\\r\\\\nJudging Criteria\\\\r\\\\n\\\\r\\\\nThis is DEV, so your write-up matters most. Submissions will be evaluated for:\\\\r\\\\n\\\\r\\\\n    Writing Quality (weighted most heavily)\\\\r\\\\n    Relevance to the Prompt and Theme\\\\r\\\\n    Creativity\\\\r\\\\n    Technical Execution\\\\r\\\\n    Use of Partner Technology (optional, for prize category entries)\\\\r\\\\n\\\\r\\\\nShow your work: saving your agent session with DevRelay and embedding it in your post is optional, but it helps the judges understand your process.\\\\r\\\\n\\\\r\\\\nPrizes 🏆\\\\r\\\\n\\\\r\\\\nOverall winner (1) will receive:\\\\r\\\\n\\\\r\\\\n    $250 USD cash prize\\\\r\\\\n    DEV++ Membership\\\\r\\\\n    Exclusive DEV Badge\\\\r\\\\n\\\\r\\\\nFeatured category winners (6) will each receive:\\\\r\\\\n\\\\r\\\\n    $200 USD cash prize\\\\r\\\\n    Exclusive DEV Badge\\\\r\\\\n\\\\r\\\\nPartner category winners (14) will each receive:\\\\r\\\\n\\\\r\\\\n    $100 USD cash prize\\\\r\\\\n    Exclusive DEV Badge\\\\r\\\\n\\\\r\\\\nAll participants with a valid submission will receive a completion badge on their DEV profile.\\\\r\\\\n\\\\r\\\\nHow To Participate\\\\r\\\\n\\\\r\\\\nPublish a post on DEV using the submission template on the challenge page and be sure to include the required challenge tag: #hf26challenge. Tell us what you built and how you interpreted the theme, show us a demo, and explain why open innovation matters for what you built.\\\\r\\\\n\\\\r\\\\nIf your app requires logging in, please provide testing credentials in your submission and/or instructions on how to best test your application for judges.\\\\r\\\\n\\\\r\\\\nImportant Dates\\\\r\\\\n\\\\r\\\\n    October 26: Hacktoberfest Open-Source AI Challenge: Week 4 begins!\\\\r\\\\n    October 31: Submissions due at 11:59 PM PDT\\\\r\\\\n    Week of November 2: Winners Announced\\\",\\\"type_of\\\":\\\"challenge\\\",\\\"starts_at\\\":\\\"2026-10-26T19:00:00.000Z\\\",\\\"ends_at\\\":\\\"2026-10-31T06:59:00.000Z\\\",\\\"published\\\":true,\\\"cover_image\\\":\\\"https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/events/cover_image/82/e4131c99-f797-42be-95ef-b55e1f04255f.png\\\",\\\"location_url\\\":null}}\"}],\"isError\":false}"
  }
]

Agent

I found a deadline mismatch while checking the live challenge details: the DEV event feed’s ends_at timestamp falls on Oct 30 at 11:59 PM PDT, while plan.md says Oct 31 at 11:59 PM PDT. I’m verifying the published challenge page before recording any submission deadline in the draft.

Agent

▸ wait {"cell_id":"174","yield_time_ms":10000,"max_tokens":500}

Input

{
  "cell_id": "174",
  "yield_time_ms": 10000,
  "max_tokens": 500
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"a31197\",\"wall_time_seconds\":1.001336572,\"session_id\":47763,\"original_token_count\":0,\"output\":\"\"}"
  }
]

Agent

The T4 gate is now exercised end to end: an interactive PTY session writes events to SQLite, the authenticated dashboard API returns those events, a live server bound on [REDACTED]:18765, the static page returned HTTP 200, and the unauthenticated API returned 401. I’m checking whether this environment permits the plan’s isolated-network test; I’ll record a failure as such rather than claim offline operation.

Agent

▸ wait {"cell_id":"184","yield_time_ms":10000,"max_tokens":800}

Input

{
  "cell_id": "184",
  "yield_time_ms": 10000,
  "max_tokens": 800
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"320a8a\",\"wall_time_seconds\":1.000869354,\"session_id\":7797,\"original_token_count\":34,\"output\":\"sudo: a terminal is required to read the password; either use the -S option to read from standard input or configure an askpass helper\\n\"}"
  }
]

Agent

The offline check is blocked by container privileges: unshare -rn true succeeds, but bringing loopback up fails with “Operation not permitted,” and the full sudo recipe cannot prompt for a password. I’ve recorded that as unverified. The challenge deadline discrepancy is resolved in favor of the official Week 4 page (Oct 31, 11:59 PM PDT); the API feed’s timestamp is one day early. I’m running the project’s local selftest now.

Agent

▸ wait {"cell_id":"199","yield_time_ms":10000,"max_tokens":400}

Input

{
  "cell_id": "199",
  "yield_time_ms": 10000,
  "max_tokens": 400
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"4c3af7\",\"wall_time_seconds\":1.00086952,\"session_id\":60109,\"original_token_count\":0,\"output\":\"\"}"
  }
]

Agent

The project selftest now passes against the pre-pulled local Gemma model. One required plan step remains outside the workspace’s granted permissions: .git is explicitly read-only, so the root project cannot be committed. I’m requesting elevated permission to create a single reviewable build commit; the earlier sandboxed git add failed before staging anything.

Agent

▸ wait {"cell_id":"202","yield_time_ms":10000,"max_tokens":1000}

Input

{
  "cell_id": "202",
  "yield_time_ms": 10000,
  "max_tokens": 1000
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"69f814\",\"wall_time_seconds\":0.00001102,\"exit_code\":0,\"original_token_count\":635,\"output\":\"warning: adding embedded git repository: demo/fixture_project\\nhint: You've added another git repository inside your current repository.\\nhint: Clones of the outer repository will not contain the contents of\\nhint: the embedded repository and will not know how to obtain it.\\nhint: If you meant to add a submodule, use:\\nhint:\\nhint: \\tgit submodule add <url> demo/fixture_project\\nhint:\\nhint: If you added this path by mistake, you can remove it from the\\nhint: index with:\\nhint:\\nhint: \\tgit rm --cached demo/fixture_project\\nhint:\\nhint: See \\\"git help submodule\\\" for more information.\\nhint: Disable this message with \\\"git config set advice.addEmbeddedRepo false\\\"\\n[main (root-commit) 7f27c8e] T0-T15: implement PhantomShell build plan\\n 41 files changed, 3121 insertions(+)\\n create mode 100644 .gitignore\\n create mode 100644 LICENSE\\n create mode 100644 PROGRESS.md\\n create mode 100644 README.md\\n create mode 160000 demo/fixture_project\\n create mode 100644 demo/script_session1.md\\n create mode 100644 demo/script_session2.md\\n create mode 100644 docs/architecture.md\\n create mode 100644 docs/claims.md\\n create mode 100644 docs/dev-post-draft.md\\n create mode 100644 docs/evaluation.md\\n create mode 100644 docs/threat-model.md\\n create mode 100644 phantomshell/__init__.py\\n create mode 100644 phantomshell/brain.py\\n create mode 100644 phantomshell/capture/__init__.py\\n create mode 100644 phantomshell/capture/hooks.sh\\n create mode 100644 phantomshell/capture/markers.py\\n create mode 100644 phantomshell/capture/pty_session.py\\n create mode 100644 phantomshell/cli.py\\n create mode 100644 phantomshell/episodes.py\\n create mode 100644 phantomshell/ingest.py\\n create mode 100644 phantomshell/investigator.py\\n create mode 100644 phantomshell/memory.py\\n create mode 100644 phantomshell/policy.py\\n create mode 100644 phantomshell/server.py\\n create mode 100644 phantomshell/static/index.html\\n create mode 100644 phantomshell/store.py\\n create mode 100644 phantomshell/tools.py\\n create mode 100644 phantomshell/verify.py\\n create mode 100644 plan.md\\n create mode 100644 pyproject.toml\\n create mode 100644 scripts/test_pty_smoke.py\\n create mode 100644 tests/security/test_brain.py\\n create mode 100644 tests/security/test_dashboard.py\\n create mode 100644 tests/security/test_tools.py\\n create mode 100644 tests/unit/test_capture.py\\n create mode 100644 tests/unit/test_episodes.py\\n create mode 100644 tests/unit/test_ingest.py\\n create mode 100644 tests/unit/test_investigator.py\\n create mode 100644 tests/unit/test_memory.py\\n create mode 100644 tests/unit/test_verifier.py\\n\"}"
  }
]

Agent

The elevated commit succeeded, but Git treated the fixture’s test-generated .git directory as an embedded repository and committed only a submodule pointer for demo/fixture_project. I need to remove that generated fixture metadata, stage the fixture files normally, and create a correction commit so clones actually contain the demo.

Agent

▸ wait {"cell_id":"204","yield_time_ms":10000,"max_tokens":500}

Input

{
  "cell_id": "204",
  "yield_time_ms": 10000,
  "max_tokens": 500
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"2c9825\",\"wall_time_seconds\":0.000008647,\"exit_code\":0,\"original_token_count\":7,\"output\":\"rm 'demo/fixture_project'\\n\"}"
  }
]

Agent

The root index now stages the fixture’s actual files instead of a gitlink. The correction is the only pending change; I’m creating a follow-up commit so the new root repository is cloneable with the demo project included.

Agent

▸ wait {"cell_id":"207","yield_time_ms":10000,"max_tokens":700}

Input

{
  "cell_id": "207",
  "yield_time_ms": 10000,
  "max_tokens": 700
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"b4ba93\",\"wall_time_seconds\":0.00001076,\"exit_code\":0,\"original_token_count\":101,\"output\":\"[main d14eaeb] Fix: track demo fixture files directly\\n 6 files changed, 52 insertions(+), 1 deletion(-)\\n delete mode 160000 demo/fixture_project\\n create mode 100644 demo/fixture_project/README.md\\n create mode 100644 demo/fixture_project/build.py\\n create mode 100644 demo/fixture_project/config.toml\\n create mode 100755 demo/fixture_project/reset.sh\\n create mode 100644 demo/fixture_project/src/main.py\\n\"}"
  }
]

Agent

The final verification now reports 24 passing unit/security tests, a passing PTY/dashboard smoke, and clean Ruff checks. I’ve updated the progress record and claim draft with those results; I’m committing this last verification update.

Agent

▸ wait {"cell_id":"216","yield_time_ms":10000,"max_tokens":700}

Input

{
  "cell_id": "216",
  "yield_time_ms": 10000,
  "max_tokens": 700
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"decfaf\",\"wall_time_seconds\":0.000011434,\"exit_code\":0,\"original_token_count\":28,\"output\":\"[main b820e58] T11-T13: record verified acceptance results\\n 5 files changed, 28 insertions(+), 7 deletions(-)\\n\"}"
  }
]

Agent

I’ve tightened the Plan prompt after the live Conclude correctly declined to support the cause but still missed the config read. I’m going to run the fixture’s two-session path once more to see whether Gemma now requests enough checks for memory and rename staleness.

Agent

▸ wait {"cell_id":"221","yield_time_ms":30000,"max_tokens":1000}

Input

{
  "cell_id": "221",
  "yield_time_ms": 30000,
  "max_tokens": 1000
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"0f8d03\",\"wall_time_seconds\":1.001601777,\"session_id\":43660,\"original_token_count\":0,\"output\":\"\"}"
  }
]

Agent

▸ wait {"cell_id":"227","yield_time_ms":30000,"max_tokens":300}

Input

{
  "cell_id": "227",
  "yield_time_ms": 30000,
  "max_tokens": 300
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"1f0b14\",\"wall_time_seconds\":1.000539524,\"session_id\":88497,\"original_token_count\":0,\"output\":\"\"}"
  }
]

Agent

▸ wait {"cell_id":"231","yield_time_ms":30000,"max_tokens":300}

Input

{
  "cell_id": "231",
  "yield_time_ms": 30000,
  "max_tokens": 300
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"e7d0c7\",\"wall_time_seconds\":1.000849245,\"session_id\":2915,\"original_token_count\":0,\"output\":\"\"}"
  }
]

Agent

▸ wait {"cell_id":"234","yield_time_ms":30000,"max_tokens":500}

Input

{
  "cell_id": "234",
  "yield_time_ms": 30000,
  "max_tokens": 500
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"168eda\",\"wall_time_seconds\":1.000545863,\"session_id\":17472,\"original_token_count\":0,\"output\":\"\"}"
  }
]

Agent

The model now requested three relevant checks, including config.toml, and the backend captured its hash. Its first Conclude still stayed inconclusive despite those results, so I’ve made the Conclude prompt explicitly compare completed checks and cite both the config entry and available tree path when they establish a mismatch. I’m rerunning Conclude on the same evidence to see whether the verifier accepts a supported result.

Agent

▸ wait {"cell_id":"238","yield_time_ms":30000,"max_tokens":300}

Input

{
  "cell_id": "238",
  "yield_time_ms": 30000,
  "max_tokens": 300
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"230a8d\",\"wall_time_seconds\":1.001509831,\"session_id\":10450,\"original_token_count\":0,\"output\":\"\"}"
  }
]

Agent

Gemma’s Conclude still returned “inconclusive” on the fixture evidence, so the live memory-promotion path remains unverified. I’ve adjusted the verifier to suppress any cause-like narrative in that case; I’m checking that change, refreshing the acceptance notes, and rerunning the requested checks.

Agent

The broader checks caught two integration issues from the latest change: the conclusion input was reshaped without updating a fake-model test, and the verifier’s inconclusive branch still leaves narrative text intact. I’m fixing both before rerunning the suite.

Agent

The code checks now pass: 25 unit/security tests, Ruff, and the PTY/dashboard smoke. The local Ollama selftest also passed after rerunning it with loopback access outside the sandbox. I’m doing the final repository cleanup and recording these results in the progress log.

Agent

▸ wait {"cell_id":"259","yield_time_ms":1000,"max_tokens":2000}

Input

{
  "cell_id": "259",
  "yield_time_ms": 1000,
  "max_tokens": 2000
}

Output

[
  {
    "type": "input_text",
    "text": "Script completed\nWall time 0.0 seconds\nOutput:\n"
  },
  {
    "type": "input_text",
    "text": "{\"chunk_id\":\"654eb5\",\"wall_time_seconds\":0.000010663,\"exit_code\":0,\"original_token_count\":69,\"output\":\"[main 08c5d36] Fix: suppress unsupported inconclusive narratives\\n 8 files changed, 44 insertions(+), 15 deletions(-)\\n08c5d36 Fix: suppress unsupported inconclusive narratives\\nb820e58 T11-T13: record verified acceptance results\\nd14eaeb Fix: track demo fixture files directly\\n\"}"
  }
]

Agent

Implemented the PhantomShell plan’s core capture, investigation, evidence verification, approval, memory, and dashboard workflows. The work is committed through 08c5d36 (Fix: suppress unsupported inconclusive narratives), and the repository is clean.

Checks: 25 unit/security tests passed; Ruff passed; the PTY/dashboard smoke passed; and the local Ollama selftest passed.

Remaining limits: The live Gemma investigation stayed inconclusive, so the full two-session memory flow remains unverified. Network-isolated execution and a clean-clone setup also remain unverified. The DEV draft is saved locally but is not ready to publish; it still needs the repository URL and demo media.

🌐 Community Wisdom

Root on Local: Threat-Modeling Local-First AI Coding Agents by @tamizuddin: informed the focus on backend tool permissions and explicit limits around offline claims.
Building a Privacy-First Local AI Assistant by @tamizuddin: informed the local-inference framing; PhantomShell’s draft avoids claiming full offline operation without an isolated-network run.
Read Full Discussion on DEV — the fetched articles had no comments.

The Hacktoberfest Week 4 challenge deadline is Oct 31, 2026 at 11:59 PM PDT. The current draft still needs its demo assets before submission.

You

<environment_context>
<current_date>2026-10-31</current_date>
<timezone>Asia/Kolkata</timezone>
<filesystem><workspace_roots><root>[PROJECT_PATH]/E8BA8138BA810472/My Folders/Hacktoberfest/Phantom-Shell</root></workspace_roots><permission_profile type="managed"><file_system type="restricted"><entry access="read"><special>:root</special></entry><entry access="write"><path>[PROJECT_PATH]/E8BA8138BA810472/My Folders/Hacktoberfest/Phantom-Shell</path></entry><entry access="write"><special>:slash_tmp</special></entry><entry access="write"><special>:tmpdir</special></entry><entry access="read"><path>[PROJECT_PATH]/E8BA8138BA810472/My Folders/Hacktoberfest/Phantom-Shell/.git</path></entry><entry access="read"><path>[PROJECT_PATH]/E8BA8138BA810472/My Folders/Hacktoberfest/Phantom-Shell/.agents</path></entry><entry access="read"><path>[PROJECT_PATH]/E8BA8138BA810472/My Folders/Hacktoberfest/Phantom-Shell/.codex</path></entry><entry access="read"><path>[PROJECT_PATH]/E8BA8138BA810472/My Folders/Hacktoberfest/Phantom-Shell/.aws</path></entry></file_system></permission_profile></filesystem>
</environment_context>

You

how to run

Agent

I’ll check the project README and CLI entry points so the run instructions match this checkout.

Agent

From the repository root, install PhantomShell in a virtual environment and pull the model:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
ollama pull gemma4:e4b

Then use two terminals, with the virtual environment activated in each:

# Terminal 1: start the dashboard
phantomshell serve

# Terminal 2: start an instrumented Bash
phantomshell run

The dashboard prints a local URL with a launch token. In the instrumented Bash, run commands as usual; captured events are saved in SQLite.

To capture just one command instead:

phantomshell run -- python build.py

To capture without model inference, add --no-model before --:

phantomshell run --no-model -- python build.py

For the demo fixture, go to demo/fixture_project, run ./reset.sh, then python build.py. The project’s README has more details.

You

is entire app implemented ?

Agent

The core app is implemented, but the full plan isn’t complete or fully verified.

The terminal capture, SQLite storage, local Ollama calls, read-only investigation tools, evidence checks, approval dashboard, and memory logic are in place. The checks run during implementation passed.

Some planned end-to-end work remains unverified: the live model’s conclusion stayed inconclusive, so memory promotion across two sessions wasn’t demonstrated. Network-isolated operation and clean-clone setup also weren’t verified.

The Spirit of It

There is something unsettling about a failure that appears to come out of nowhere.

You rerun the command. It fails again. You inspect the logs, change a configuration, try another command, and eventually discover that the answer was hiding in something you had already seen.

The machine has been telling you what happened all along. The problem is that the evidence is fragmented, the context disappears, and yesterday's solution becomes tomorrow's mystery.

That is the ghost I wanted to explore.

Phantom-Shell is an attempt to give those forgotten failures a memory — and to make the process of understanding them more systematic.

Not an AI that magically knows every answer, but one that can help gather clues, explain its reasoning, acknowledge uncertainty, and leave the final decision with the developer.

The terminal remembers. Now it is time to investigate.

# RepoMoss

Niranjan R Soorej — Sun, 25 Oct 2026 19:37:35 +0000

RepoMoss 🌱 — You Build What's Next. RepoMoss Tends to What You've Left Behind.

Every developer knows the feeling.

You finish a feature, fix a bug, merge a pull request, and move on to the next exciting thing. But somewhere in your repository, small things start piling up.

A broken link in the README.
A TODO comment that has been sitting there for months.
Documentation that needs attention.
Small maintenance tasks that never feel urgent enough to prioritize.

Individually, these problems seem harmless. Over time, they make a codebase harder to understand and maintain.

For the DEV Community Hacktoberfest Challenge Week 3 — “Slow and Steady,” I built RepoMoss, a local-first AI-assisted codebase maintenance tool designed to help developers take care of these neglected tasks in small, controlled steps.

🔗 GitHub Repository: https://github.com/NiranjanRSoorej06/RepoMoss

🌱 What is RepoMoss?

RepoMoss scans a Git repository for a limited set of maintenance issues, organizes findings into a reviewable queue, and can attempt a narrow documentation repair in an isolated Git worktree.

The idea is simple:

Instead of waiting for a developer to notice every small maintenance problem, help them discover and address those problems before they accumulate.

RepoMoss isn't designed to replace developers or autonomously rewrite entire codebases. It focuses on small, evidence-backed tasks that can be inspected and verified.

✨ What can it do today?

The current MVP includes:

1. Repository validation

2. Maintenance scanning

Detect TODO, FIXME, and XXX markers in Markdown files, along with broken relative links in Markdown documentation.

3. Evidence-backed findings

Each finding includes its file references, relevant evidence, category, priority, risk, and a proposed plan. Findings are surfaced for review rather than blindly treated as defects.

4. Optional local AI explanations

RepoMoss can use a model served through Ollama to explain findings. If Ollama is unavailable, a deterministic fallback keeps the core workflow usable.

5. Human-controlled execution

Review a finding and explicitly approve an attempt before RepoMoss starts working on it. Findings can also be deferred or rejected.

6. Isolated documentation repair

For a supported broken-link case, RepoMoss can attempt a bounded repair in a separate Git worktree instead of editing your original checkout.

7. Controlled verification and reporting

Verification commands must be explicitly configured by the operator and must match the configured allowlist. RepoMoss records the resulting diff, logs, and report so developers can inspect what happened.

The important distinction is that a generated plan or patch is not automatically a successful fix. Actual results and verification output matter.

🧠 Why use open-weight AI?

For RepoMoss, open-weight AI is about more than generating explanations.

It gives developers the flexibility to run compatible models locally, choose a model that suits their hardware and requirements, and avoid sending repository evidence to a hosted inference API by default.

RepoMoss is designed around local-first operation:

Repository scanning happens locally.
SQLite stores task and scan history locally.
Optional model explanations use Ollama.
Repository evidence is not sent to a hosted inference API by RepoMoss.
The core scanner can work without a model connection.

This matters for personal projects, student repositories, and private codebases where developers may prefer to keep their work on their own machines.

Open-weight models also make experimentation more accessible. Developers can explore different models and trade-offs without having to redesign the entire maintenance workflow around a single hosted AI provider.

Of course, local inference still consumes hardware resources, and open weights do not automatically mean that every part of a model's training process or licensing is fully open source.

🛡️ Safety is part of the design

An AI maintenance tool should not be trusted simply because it sounds confident.

RepoMoss follows a deliberately constrained approach:

No automatic merging: it never merges or pushes changes.
No edits to the original checkout: attempted changes are kept in a separate Git worktree.
Explicit approval: a task must be approved before an attempt begins.
No model-generated shell commands: the model explains findings but cannot issue commands or provide executable patches in this MVP.
Opt-in verification: no verification commands run by default.
Bounded scanning: common dependency and build directories, symlinks, likely secrets, oversized files, and excessive file counts are handled conservatively.
Transparent outcomes: diffs, logs, and reports help developers review the attempt.

These protections reduce risk, but they are not a substitute for a proper operating-system sandbox. Git worktrees isolate changes from the original checkout; they do not make arbitrary repository code safe to execute. Verification commands should therefore be configured carefully.

🛠️ Tech stack

RepoMoss currently uses:

Python + FastAPI for the backend and API.
HTML, CSS, and JavaScript for the lightweight dashboard.
SQLite for local persistence.
Git and Git worktrees for repository inspection and isolated changes.
Ollama for optional local model inference.
Pydantic for structured data and validation.

The architecture intentionally keeps the core maintenance workflow useful even when the optional model service is unavailable.

🔄 How the workflow works

The core workflow follows a simple sequence:

Register a local Git repository.
Scan for supported maintenance issues.
Review the findings and their evidence.
Request an optional local-model explanation.
Approve a suitable task.
Attempt the supported repair in an isolated worktree.
Optionally run explicitly allowlisted verification commands.
Review the diff, logs, and Markdown report.

The goal isn't to make maintenance completely invisible. It is to make it easier to start, easier to review, and less likely to be forgotten.

🚧 Current limitations and what's next

RepoMoss is an MVP, not a fully autonomous coding agent.

Currently, its scanner focuses on a small set of Markdown maintenance issues. TODO findings are available for review but are not automatically patched. The supported repair is deliberately narrow: converting a broken local Markdown link into its visible plain-text label.

Broader code repairs, automatic test generation, scheduled maintenance, cancellation, automatic merging, and OS-level sandboxing are not implemented.

Future improvements could include:

More deterministic maintenance checks.
Additional safe documentation repairs.
Better repository-specific verification profiles.
Richer maintenance reports and historical trends.
More evaluation across real-world repositories.
Additional model options and configurable task policies.

I'd rather build a small tool that clearly reports what it did than a broad agent that claims success without enough evidence.

💚 Why this project fits “Slow and Steady”

The theme resonates with the problem RepoMoss is trying to solve.

Software maintenance rarely consists of one dramatic moment. It is a collection of small decisions and small tasks repeated over time.

RepoMoss applies that philosophy to both the problem and the solution: find manageable tasks, attempt them in isolation, verify what happened, and leave the final decision with the developer.

It also reflects why open innovation matters to me. Local models, accessible tooling, and open repositories give developers room to experiment with different approaches instead of depending entirely on a closed service.

The result is not an AI that takes control of your repository. It is a tool that helps you pay attention to the parts of your project that are easy to overlook.

🙌 Try it out

The project is available here:

🔗 Repository: https://github.com/NiranjanRSoorej06/RepoMoss

The README contains local setup instructions, verification configuration, security notes, and the current MVP feature list.

If you try RepoMoss, I'd love feedback on which maintenance checks would be most useful, what safety controls you would want before trusting an automated repair, and how you would evaluate whether a maintenance assistant is genuinely helping.

You build what's next. RepoMoss tends to what you've left behind. 🌱

HustlePilot

Niranjan R Soorej — Mon, 19 Oct 2026 06:53:13 +0000

HustlePilot: an AI copilot for small businesses that is not allowed to invent numbers

Draft DEV post for Hacktoberfest 2026. AI disclosure: this project and this draft were built with agent assistance (some_ai).

Small sellers — a plant nursery in this case — already have data: WhatsApp order notes, a sales CSV, a products sheet. What they don't have is time to read it every morning. HustlePilot is a local-first AI copilot that turns three CSVs into a ranked morning briefing: what's running low, what's slowing down, which inquiries went cold, and which listings are thin.

The interesting part isn't the LLM. It's the rules around it.

The one design rule: code computes, the LLM writes

Every number you see in HustlePilot — stock cover, sales rate ratios, days waiting on an inquiry — is computed by deterministic pandas rules (backend/app/services/analytics.py). The LLM's only job is to turn that evidence into a sentence a human would write.

And it may only reuse numbers that appear in the evidence. Before any narrative reaches the UI, a grounding validator (backend/app/services/grounding.py) extracts every number from the LLM's text and checks it against the evidence dict:

def safe_narrative(opp_type, evidence, llm_text, extra=None):
    """Return (narrative, source, rejected_numbers)."""
    if llm_text:
        bad = ungrounded_numbers(llm_text, evidence, extra)
        if not bad:
            return llm_text.strip(), "llm", []
        return TEMPLATES[opp_type], "template", sorted(bad)
    return TEMPLATES[opp_type], "template", []

If the model says "you sold 94 units last week" and the evidence says 14, the whole narrative is replaced with a boring-but-true template, the rejection is counted, and the UI labels the source (llm vs template). The model can't quietly delete a bad number — the entire text is forfeited. That's on purpose: partial edits are harder to audit than all-or-nothing fallback.

This mirrors a pattern the community keeps re-learning: search-enabled or retrieval-enabled LLMs still get numbers wrong, because retrieval fixes access to facts, not faithfulness in restating them (Why Search-Enabled LLMs Still Get Numbers Wrong 👤 @yany-henry). A validator at the output boundary is the part that actually enforces it (Why your AI agent keeps hallucinating financial data (and how to fix it) 👤 @valyuai).

Screenshots

Architecture in one screen

Backend: FastAPI + SQLite (single file, tenant-scoped rows with a business_id, demo API-key auth — it's a single-tenant demo, not multi-tenant SaaS).
LLM: any Ollama-compatible endpoint (gemma3:4b locally) or a deterministic mock. Every provider response is labeled real/mock in the UI. No GPU required; inference runs CPU-bound on a laptop.
Frontend: React + Vite + Tailwind. Dashboard, CSV import with validation reports, opportunity feed, listing studio, inquiry inbox, approvals queue (draft → approved → exported), history timeline.
Eval harness (eval/run_eval.py): five stages — CSV-defect injection, a hand-computed rules fixture, grounding unit checks, labeled inquiry classification vs. a keyword baseline, and latency.

The approval queue matters more than it sounds. Generated drafts never send themselves: an inquiry reply or listing draft sits as submitted until the owner approves, edits, or dismisses it. Every state change is audited.

What the eval actually measured

Honest numbers, with sample sizes:

Stage	Result
CSV validation, 30 injected defects	30/30 detected, 0 errors on clean files
Rules fixture (hand-computed expectations)	14/14 checks pass
Grounding unit checks	7/7 (fabricated numbers rejected, ratio edge cases, URL flagging)
Backend tests (`pytest`, mock providers)	35 passed
API smoke (end-to-end through HTTP)	36/36 checks pass
Real-model latency (gemma3:4b, CPU, n=1)	analyze ≈ 77 s · listing ≈ 50 s · inquiry ≈ 56 s

What was not measured, and I'm not going to pretend otherwise: listing-copy quality has no human rating yet; classification accuracy against the labeled fixture is a small-n, single-domain test; and the before/after comparison view in the app is correlational — nothing in HustlePilot claims an action caused a sale. The rules carry honest limitations text on every opportunity for exactly this reason.

Small things that saved the demo

AS_OF is derived from max(sale_date), not today's clock — demos are reproducible, and "days waiting" doesn't drift between rehearsals.
Slow-mover analysis refuses to run with fewer than recent + baseline days of history (112 by default) and says so in a notice, instead of quietly computing nonsense on two weeks of data.
Mock everything, label everything. LLM_PROVIDER=mock and SEARCH_PROVIDER=mock make the full stack testable in CI, and the UI never lets a mock output masquerade as a real one.
>20% invalid rows rejects the whole CSV with an explanation, rather than importing the silent majority.

Run it

# backend
cd backend && pip install -r requirements.txt
cp ../.env.example ../.env   # LLM_PROVIDER=ollama, SEARCH_PROVIDER=mock
uvicorn app.main:app --reload

# frontend
cd frontend && npm install && npm run dev   # proxies /api → :8000

# tests + eval
LLM_PROVIDER=mock SEARCH_PROVIDER=mock pytest -q
python eval/run_eval.py --stage validation --llm mock
python eval/run_eval.py --stage classification --llm real --limit 12

Hit Import sample data in the UI to load a fictional Bengaluru plant nursery (8 products, 619 sales, 5 inquiries).

TL;DR

An LLM that writes your morning briefing is a liability. An LLM that writes your morning briefing under a numeric grounding check, behind an approval queue, with every fallback visible in the UI is a tool. Code computes; the LLM narrates; the human decides.

Built for Hacktoberfest 2026. Feedback, PRs, and "you should have used X instead" all welcome.

🌱 GrowMate: Your Local AI Gardening Companion with Gemma 3 4B | Hacktoberfest 2026

Niranjan R Soorej — Mon, 12 Oct 2026 06:45:21 +0000

🌱 GrowMate: Your Local AI Gardening Companion with Gemma 3 4B | Hacktoberfest 2026

What if AI could help us spend less time staring at screens and more time taking care of the world around us?

For the Hacktoberfest 2026 — “Touch Grass” challenge, I'm building GrowMate, an AI-powered gardening companion designed to make gardening more approachable through local AI.

🌿 GitHub Repository: NiranjanRSoorej06/growmate

🤖 AI Model: Gemma 3 4B via Ollama

🌿 The Idea

Starting a garden can feel overwhelming, especially for beginners. Which plants should you grow? How often should you water them? What should you do when a plant looks unhealthy?

GrowMate aims to make these questions easier to tackle through an accessible web interface and AI-assisted gardening guidance.

The goal is to use technology to help people learn about plants and turn that knowledge into real-world action.

🤖 Why Gemma 3 4B?

GrowMate uses Gemma 3 4B through Ollama for local AI experimentation.

Running a model locally offers several advantages:

Privacy: Requests can be processed locally rather than automatically sent to a third-party AI API.
Control: The model can be integrated into a custom backend and application workflow.
Accessibility: Developers can experiment with open models without depending entirely on paid proprietary APIs.
Learning: Local inference provides hands-on experience with AI integration and deployment.

Local inference also has trade-offs, including hardware requirements and response latency.

🛠️ Tech Stack

Component	Technology
Frontend	React, Vite, Tailwind CSS
Backend	Python, FastAPI
AI model	Gemma 3 4B
Model runtime	Ollama
Database	SQLite
Deployment	Render configuration in progress

The frontend communicates with the FastAPI backend, which handles application logic and connects to Ollama for AI inference.

🔄 How It Works

A user submits a gardening question through the frontend.
The frontend sends the request to FastAPI.
The backend communicates with the configured Ollama model.
The generated response is returned to the frontend.
The user can apply the guidance to their gardening activities.

The broader vision includes gardening guidance, planting plans, plant-care assistance, and a gardening journal. These capabilities will be developed and verified as the project progresses.

💻 Running Locally

Ensure Ollama is running and the model is available:

ollama pull gemma3:4b
ollama list

Start the backend from the backend directory with your Python virtual environment activated:

uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

In a separate terminal, start the frontend:

cd frontend
npm install
npm run dev

Open the local URL printed by Vite, usually http://localhost:5173.

For local AI inference, configure the backend to use:

OLLAMA_URL=http://localhost:11434

Keep real environment files and credentials out of version control.

☁️ Deployment Challenges

I'm preparing GrowMate for deployment on Render.

One important lesson is that deploying an application does not automatically deploy its AI model. Inside a cloud container, localhost:11434 refers to the container itself, not Ollama running on my laptop.

Hosted AI requests require a separately reachable Ollama server. This is one of the infrastructure challenges I'm working through as I prepare the project for production.

🌍 Why “Touch Grass”?

AI is often used to help us do more work on our computers. But what if it could also encourage us to spend more time away from them?

A gardening assistant should ultimately help someone take practical action: water a plant, learn about sunlight requirements, prepare soil, or develop a habit of caring for something living.

The goal is to make AI a bridge between digital knowledge and real-world activity.

🚧 What's Next?

Improve gardening guidance and the user experience.
Continue testing local Gemma and Ollama integration.
Verify backend health checks and database persistence.
Complete the Render deployment configuration.
Configure reachable inference infrastructure for hosted AI.
Test the complete workflow from asking a question to applying the advice.

🤝 Explore the Project

🌱 GitHub: https://github.com/NiranjanRSoorej06/growmate

I'm interested in feedback, suggestions, and contributions that could make GrowMate more useful for beginners and gardening enthusiasts.

🧑‍💻 Build Process

I also documented my development workflow through a DevRelay build session.

🔗 Explore the GrowMate build session on Dev.to

This provides additional context on the implementation process and the technical decisions behind the project.

💚 Final Thoughts

GrowMate is my experiment in combining open AI models with an everyday activity that gets us away from our screens.

The interesting part isn't just making a model answer questions. It's building an application that helps turn those answers into practical action.

If you were building an AI project to help people spend more time outdoors, what would you create? I'd love to hear your ideas in the comments!

Project: GrowMate

Model: Gemma 3 4B via Ollama

Challenge: Hacktoberfest 2026 — Touch Grass

📸 Project Screenshots

# PrepMate: Your Private AI Interview Partner

Niranjan R Soorej — Mon, 05 Oct 2026 05:28:50 +0000

PrepMate: Your Private AI Interview Partner

GitHub: NiranjanRSoorej06/Prepmate

The Problem

Preparing for software engineering interviews is often frustrating for one simple reason: generic practice doesn't feel like a real interview.

Most AI interview tools can ask questions, but they don't truly understand the candidate behind the resume. A candidate may know how to build a project but struggle to explain their technical decisions, defend a claim on their resume, or respond when an interviewer digs deeper.

I wanted to build something different for a real friend preparing for software engineering interviews:

an AI interviewer that actually knows their resume and adapts to them.

The Solution

PrepMate is a private AI interview partner powered by Google's open-weight Gemma model, running locally through Ollama.

The candidate uploads their resume, and PrepMate turns it into a structured candidate profile containing their:

Skills
Projects
Education
Coursework
Activities
Technical experience

Gemma then uses that profile to conduct a personalized interview.

Instead of asking:

"What is JWT?"

PrepMate can ask:

"You mentioned implementing JWT authentication in your Content Sharing Application. What security challenges did you consider when designing your JWT strategy?"

The interview then becomes adaptive.

The candidate answers → Gemma evaluates the answer → identifies weaknesses → generates a targeted follow-up → continues the interview.

What Makes PrepMate Different

1. Resume-Aware Interviews

PrepMate doesn't treat every candidate the same.

It uses the candidate's actual resume to determine what to ask.

For example, if a resume says:

"Optimized MongoDB queries using indexing for improved performance"

PrepMate can challenge that claim by asking:

"Which queries were slow before indexing, what index did you add, and how did you measure the improvement?"

The candidate has to defend what they actually wrote.

2. Adaptive Follow-Ups

PrepMate doesn't simply move from Question 1 → Question 2 → Question 3.

After every answer, Gemma evaluates:

Technical accuracy
Communication
Depth
Strengths
Weaknesses
Topics to revise

It then generates a targeted follow-up based on the candidate's weakest or most interesting area.

This creates a real interview loop:

Question
   ↓
Answer
   ↓
Gemma Evaluation
   ↓
Weakness Identified
   ↓
Targeted Follow-up
   ↓
Answer
   ↓
Deeper Evaluation

3. Resume Attack Mode

One of PrepMate's core ideas is Resume Attack Mode.

Instead of helping candidates memorize interview questions, PrepMate challenges the claims they put on their resume.

Claims such as:

"Optimized database queries"
"Implemented secure authentication"
"Built 10+ REST APIs"
"Solved 250+ DSA problems"
"Improved performance"

become opportunities for deeper technical questioning.

The goal isn't to accuse the candidate of lying.

The goal is to answer the question:

Can you actually defend the technical claims on your resume?

Why Gemma?

Gemma is at the core of PrepMate rather than being added as an optional feature.

The local Gemma model powers multiple stages:

Resume
   ↓
Gemma → Candidate Profile
   ↓
Gemma → Interview Question
   ↓
Candidate Answer
   ↓
Gemma → Evaluation
   ↓
Gemma → Follow-up
   ↓
Gemma → Resume Challenge
   ↓
Gemma → Final Interview Report

PrepMate runs Gemma 3 4B through Ollama locally.

This also gives the project an important privacy property.

Privacy First

A resume contains personal information.

Interview preparation can contain even more sensitive information: weaknesses, mistakes, confidence levels, and areas the candidate needs to improve.

Instead of sending this preparation data to a remote LLM API, PrepMate can run the AI locally:

Resume
   ↓
Your Computer
   ↓
Ollama
   ↓
Gemma

This makes PrepMate suitable for private interview preparation without requiring the candidate's resume and answers to leave their machine.

Technical Architecture

Frontend

React
Vite
Tailwind CSS
Axios

Backend

Python
FastAPI

AI

Gemma 3 4B
Ollama

Resume Processing

PyMuPDF
Tesseract OCR
Pillow

Storage

Browser localStorage for interview session persistence

Architecture

                  ┌───────────────┐
                  │   Resume PDF  │
                  └───────┬───────┘
                          ↓
                 ┌─────────────────┐
                 │ PyMuPDF + OCR   │
                 └────────┬────────┘
                          ↓
                 ┌─────────────────┐
                 │      Gemma      │
                 │ Resume Profiler │
                 └────────┬────────┘
                          ↓
                 ┌─────────────────┐
                 │ Candidate       │
                 │ Profile         │
                 └────────┬────────┘
                          ↓
                 ┌─────────────────┐
                 │ Interview       │
                 │ Engine          │
                 └────────┬────────┘
                          ↓
                    Question
                          ↓
                       Answer
                          ↓
                 ┌─────────────────┐
                 │ Gemma Evaluator │
                 └────────┬────────┘
                          ↓
              ┌───────────┼───────────┐
              ↓           ↓           ↓
           Scores     Weaknesses  Follow-up
                                      ↓
                              Next Question

What My Friend Said

I built this for my friend Athul K, who is preparing for placements. Generic interview practice wasn’t working for him because it didn’t provide enough personalized feedback or simulate the pressure of a real interview.

After trying it, he said: “It felt much more like a real interview, and the feedback actually helped me understand what I need to improve.”

What I Learned

Building PrepMate highlighted an important distinction between an AI chatbot and an AI application.

A chatbot can generate a question.

An interview system needs to maintain context, history, evaluation, and adaptation.

The difficult part wasn't simply connecting Gemma to an API. It was designing the feedback loop around the model:

Context → Question → Answer → Evaluation → Decision → Follow-up

That loop is what turns a model into an actual interview partner.

Future Improvements

Future versions can extend PrepMate with:

Voice-based interviews
Interview performance analytics
Long-term preparation tracking
More advanced resume claim analysis
Company-specific interview modes
Interview difficulty progression
Detailed final preparation plans

But the current version focuses on the core experience:

Upload your resume. Face an interviewer that knows it. Defend what you wrote. Learn where you need to improve.

Tech Stack

React + Vite + Tailwind
          │
          ▼
       FastAPI
          │
          ▼
       Ollama
          │
          ▼
     Gemma 3 4B
          │
          ▼
Resume Profiling
Interview Generation
Answer Evaluation
Adaptive Follow-ups
Resume Attack

Running Locally

Clone the repo first:

git clone https://github.com/NiranjanRSoorej06/Prepmate.git
cd Prepmate

Start Gemma

ollama pull gemma3:4b

Start the Backend

cd backend
source .venv/bin/activate
uvicorn main:app --reload --port 8000

Start the Frontend

cd frontend
npm install
npm run dev

Then open:

http://localhost:5173

Demo Flow

Upload a resume.
Let Gemma analyze the candidate profile.
Select the target role and interview type.
Start the interview.
Answer a personalized question.
Receive technical evaluation.
Follow the targeted question generated from the weakness.
Continue the adaptive interview.
Use Resume Attack Mode to defend claims from the resume.
Refresh the browser and restore the interview session.

Why Open Models Made This Possible

PrepMate only works the way it does because Gemma is open-weight.

Your resume never leaves your machine. A resume holds your name, projects, and contact details, and interview practice holds your weaknesses. With a closed API, all of that goes to a server you don't control. With Gemma on Ollama, every model call goes to localhost, and the interview keeps working with Wi-Fi switched off.
It costs nothing to run. Practice interviews are repetitive by nature: five questions, five evaluations, five follow-ups, over and over. A paid API would charge for every attempt. A local model lets my friend practice as many times as they want.
I could shape the model's behavior. Because I control the prompts and the model, I could make Gemma act as an evaluator instead of a chatbot and return structured scores, weaknesses, and follow-ups.
It runs on a normal laptop. Gemma 3 4B is small enough for a student laptop, even on CPU, which is where most placement candidates are practicing.

Why PrepMate?

PrepMate doesn't just ask interview questions.

It asks:

"What did you claim you know, and can you actually defend it?"

It turns a static resume into a dynamic interview.

And because the intelligence runs locally with Gemma, the candidate can practice privately on their own machine.