closecode-ai 0.1.0__tar.gz

closecode_ai-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: closecode-ai
+Version: 0.1.0
+Summary: CloseCode — an agentic terminal coding assistant (LangGraph + OpenRouter + MCP)
+Author: Om Gite
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: langchain
+Requires-Dist: langgraph
+Requires-Dist: langchain-huggingface
+Requires-Dist: langsmith
+Requires-Dist: huggingface_hub
+Requires-Dist: python-dotenv
+Requires-Dist: requests
+Requires-Dist: langchain-openai
+Requires-Dist: langchain-mcp-adapters
+Requires-Dist: mcp-server-git
+Requires-Dist: langchain-openrouter
+Requires-Dist: rich
+Requires-Dist: pyfiglet
+
+# terminal-agent
+
+A minimal terminal coding agent built with LangGraph (agent loop), LangChain
+(tool + model abstraction), LangSmith (tracing), and a Hugging Face model as
+the LLM. Same shape as OpenCode/Terminus 2: read task -> decide -> run tool ->
+observe result -> repeat.
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+cp .env.example .env
+```
+
+Edit `.env`:
+- `HUGGINGFACEHUB_API_TOKEN` — from https://huggingface.co/settings/tokens
+- `HF_MODEL_ID` — a model that supports tool/function calling (see note below)
+- `LANGCHAIN_API_KEY` — optional, from https://smith.langchain.com, enables tracing
+
+## Run
+
+```bash
+python main.py
+```
+
+If `OPENROUTER_API_KEY` isn't set (env or `.env`), the agent prompts you to
+paste one at startup — input is hidden — and offers to save it to `.env`
+for next time. You can rotate it later with the `/key` command.
+
+## Switching models
+
+```text
+/models            list all OpenRouter models (● = current, free first)
+/models qwen       filter the list by name
+/models --refresh  force a fresh fetch (list is cached for 24h)
+/model 12          switch by list number
+/model qwen/qwen-2.5-72b-instruct   or any OpenRouter model id directly
+```
+
+The list comes live from OpenRouter's API and is cached for 24 hours in
+`~/.cache/closecode/`; if you're offline it falls back to a curated
+shortlist. The model choice is saved per session, so `/resume` restores
+the model you were using. Free-tier `:free` models cost nothing; check
+https://openrouter.ai/models for paid-model pricing before switching.
+
+The agent operates inside `./sandbox` (configurable via `AGENT_WORKDIR`) and
+will ask for permission before running shell commands or writing files,
+unless `AGENT_AUTO_APPROVE=true`.
+
+## Persistent sessions (SQLite)
+
+Conversations are stored in `./sessions/sessions.db` as per-message rows plus
+session metadata (name, model, mode, created/updated timestamps, message
+count). Existing `session_*.json` files are auto-migrated into the DB on the
+first run.
+
+- `--continue` — resume the most recently used session (its mode/model are
+  restored from metadata).
+- `/sessions` — list all saved sessions with metadata.
+- `/resume <id>` — switch to a saved conversation.
+- `/delete <id>` — delete a saved session.
+- Each turn is saved automatically; a session's name is derived from its
+  first user message.
+
+## Guardrails
+
+The agent is scoped to coding only, and `guardrails.py` enforces that with
+four layers:
+
+1. **Input scope** — off-topic chatter (greetings, opinions, trivia, creative
+   writing, news takes) is redirected to a coding task, and clearly malicious
+   requests (keyloggers, account hacking, phishing kits) are refused before
+   they reach the model.
+2. **Command blocking** — destructive shells commands (`rm -rf /`, `mkfs`,
+   disk wipes, fork bombs, `curl | sh`, reverse shells) are blocked before
+   execution, *even when auto-approve is on*.
+3. **Write scanning** — file writes/edits containing malware indicators
+   (ransomware, keyloggers, miners, persistence, injection) are refused.
+4. **Output redaction** — the model's final answer is scanned and flagged
+   content is scrubbed from conversation history.
+
+These are conservative heuristics on top of the sandbox + per-action
+permission prompts, not a hard guarantee. Set `AGENT_DISABLE_GUARDRAILS=true`
+in `.env` to disable them entirely (only for trusted, isolated testing).
+
+## A note on model choice
+
+Tool-calling reliability varies significantly across open Hugging Face
+models — this is the single biggest factor in whether this agent actually
+works well. Frontier closed models (what Claude Code / OpenCode use by
+default) are heavily trained specifically for reliable tool use; open models
+are improving but inconsistent.
+
+Models worth trying, roughly in order of tool-calling reliability:
+- `Qwen/Qwen2.5-72B-Instruct`
+- `meta-llama/Meta-Llama-3.1-70B-Instruct`
+- `meta-llama/Meta-Llama-3.1-8B-Instruct` (fastest/cheapest, least reliable)
+
+If a smaller model frequently fails to call tools correctly, or hallucinates
+tool arguments, that's expected — it's a real, documented gap between open
+and closed models on agentic tasks, not a bug in this code. Swapping
+`HF_MODEL_ID` is the first thing to try before changing anything else.
+
+## Where to go next
+
+1. **Watch a trace in LangSmith** (smith.langchain.com) once you have a run —
+   seeing the exact messages/tool calls at each step is the fastest way to
+   debug why the agent did something unexpected.
+2. **Add more tools** — `list_dir`, `edit_file` (targeted find/replace instead
+   of full overwrite), `run_tests`.
+3. **Split client/server** — move `build_graph()` behind a small FastAPI/
+   WebSocket server, and make `main.py` a thin client that streams from it.
+   This is the step that makes it architecturally closer to OpenCode.
+4. **Swap the sandbox for Docker** — the current harness restricts file paths
+   but shell commands still run on your actual machine. For anything beyond
+   personal experimentation, run `bash` calls inside a container instead.

closecode_ai-0.1.0/README.md

@@ -0,0 +1,116 @@
+# terminal-agent
+
+A minimal terminal coding agent built with LangGraph (agent loop), LangChain
+(tool + model abstraction), LangSmith (tracing), and a Hugging Face model as
+the LLM. Same shape as OpenCode/Terminus 2: read task -> decide -> run tool ->
+observe result -> repeat.
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+cp .env.example .env
+```
+
+Edit `.env`:
+- `HUGGINGFACEHUB_API_TOKEN` — from https://huggingface.co/settings/tokens
+- `HF_MODEL_ID` — a model that supports tool/function calling (see note below)
+- `LANGCHAIN_API_KEY` — optional, from https://smith.langchain.com, enables tracing
+
+## Run
+
+```bash
+python main.py
+```
+
+If `OPENROUTER_API_KEY` isn't set (env or `.env`), the agent prompts you to
+paste one at startup — input is hidden — and offers to save it to `.env`
+for next time. You can rotate it later with the `/key` command.
+
+## Switching models
+
+```text
+/models            list all OpenRouter models (● = current, free first)
+/models qwen       filter the list by name
+/models --refresh  force a fresh fetch (list is cached for 24h)
+/model 12          switch by list number
+/model qwen/qwen-2.5-72b-instruct   or any OpenRouter model id directly
+```
+
+The list comes live from OpenRouter's API and is cached for 24 hours in
+`~/.cache/closecode/`; if you're offline it falls back to a curated
+shortlist. The model choice is saved per session, so `/resume` restores
+the model you were using. Free-tier `:free` models cost nothing; check
+https://openrouter.ai/models for paid-model pricing before switching.
+
+The agent operates inside `./sandbox` (configurable via `AGENT_WORKDIR`) and
+will ask for permission before running shell commands or writing files,
+unless `AGENT_AUTO_APPROVE=true`.
+
+## Persistent sessions (SQLite)
+
+Conversations are stored in `./sessions/sessions.db` as per-message rows plus
+session metadata (name, model, mode, created/updated timestamps, message
+count). Existing `session_*.json` files are auto-migrated into the DB on the
+first run.
+
+- `--continue` — resume the most recently used session (its mode/model are
+  restored from metadata).
+- `/sessions` — list all saved sessions with metadata.
+- `/resume <id>` — switch to a saved conversation.
+- `/delete <id>` — delete a saved session.
+- Each turn is saved automatically; a session's name is derived from its
+  first user message.
+
+## Guardrails
+
+The agent is scoped to coding only, and `guardrails.py` enforces that with
+four layers:
+
+1. **Input scope** — off-topic chatter (greetings, opinions, trivia, creative
+   writing, news takes) is redirected to a coding task, and clearly malicious
+   requests (keyloggers, account hacking, phishing kits) are refused before
+   they reach the model.
+2. **Command blocking** — destructive shells commands (`rm -rf /`, `mkfs`,
+   disk wipes, fork bombs, `curl | sh`, reverse shells) are blocked before
+   execution, *even when auto-approve is on*.
+3. **Write scanning** — file writes/edits containing malware indicators
+   (ransomware, keyloggers, miners, persistence, injection) are refused.
+4. **Output redaction** — the model's final answer is scanned and flagged
+   content is scrubbed from conversation history.
+
+These are conservative heuristics on top of the sandbox + per-action
+permission prompts, not a hard guarantee. Set `AGENT_DISABLE_GUARDRAILS=true`
+in `.env` to disable them entirely (only for trusted, isolated testing).
+
+## A note on model choice
+
+Tool-calling reliability varies significantly across open Hugging Face
+models — this is the single biggest factor in whether this agent actually
+works well. Frontier closed models (what Claude Code / OpenCode use by
+default) are heavily trained specifically for reliable tool use; open models
+are improving but inconsistent.
+
+Models worth trying, roughly in order of tool-calling reliability:
+- `Qwen/Qwen2.5-72B-Instruct`
+- `meta-llama/Meta-Llama-3.1-70B-Instruct`
+- `meta-llama/Meta-Llama-3.1-8B-Instruct` (fastest/cheapest, least reliable)
+
+If a smaller model frequently fails to call tools correctly, or hallucinates
+tool arguments, that's expected — it's a real, documented gap between open
+and closed models on agentic tasks, not a bug in this code. Swapping
+`HF_MODEL_ID` is the first thing to try before changing anything else.
+
+## Where to go next
+
+1. **Watch a trace in LangSmith** (smith.langchain.com) once you have a run —
+   seeing the exact messages/tool calls at each step is the fastest way to
+   debug why the agent did something unexpected.
+2. **Add more tools** — `list_dir`, `edit_file` (targeted find/replace instead
+   of full overwrite), `run_tests`.
+3. **Split client/server** — move `build_graph()` behind a small FastAPI/
+   WebSocket server, and make `main.py` a thin client that streams from it.
+   This is the step that makes it architecturally closer to OpenCode.
+4. **Swap the sandbox for Docker** — the current harness restricts file paths
+   but shell commands still run on your actual machine. For anything beyond
+   personal experimentation, run `bash` calls inside a container instead.

closecode_ai-0.1.0/agent.py

@@ -0,0 +1,74 @@
+
+from typing import Annotated, TypedDict
+
+from langgraph.graph import StateGraph
+from langgraph.graph.message import add_messages
+from langgraph.prebuilt import ToolNode, tools_condition
+
+from llm import get_llm
+
+SYSTEM_PROMPT = """You are a terminal coding agent running in a sandboxed working directory.
+You have tools for reading, writing, and editing files, running shell commands and tests,
+listing directories, and interacting with git (status, diff, log, commit, branches).
+
+Note: your available tools change depending on the current mode. In "plan" mode only
+read-only tools are bound to you (you literally cannot call write/edit/bash/commit tools
+even if you wanted to) — use that mode to explore and propose an approach without any
+risk of side effects. In "build" mode all tools are available.
+
+Rules:
+- Inspect before you change: look at relevant files or run a command to understand
+  the current state before editing anything.
+- Prefer edit_file over write_file for small changes — it's cheaper and safer than
+  rewriting a whole file.
+- Call one tool at a time and read its result before deciding the next step.
+- Verify your work: after making a change, run a command, run tests, or read the
+  file back to confirm it did what you intended. Never report a task complete
+  without verifying — bugs are unacceptable, so test before you say "done".
+- Use git tools deliberately: check status/diff before committing, and never force-push
+  or hard-reset unless the user explicitly asked for that specific action.
+- When the task is complete, reply with plain text summarizing what you did.
+  Do not call a tool in the same turn as your final summary.
+
+Scope & safety:
+- You are a coding assistant, not a general chat assistant. If the user asks for
+  something unrelated to code (greetings, small-talk, opinions, news, games,
+  creative writing, trivia), politely redirect them back to a concrete coding task
+  instead of entertaining it.
+- Never write working malware, ransomware, keyloggers, reverse shells, credential
+  stealers, or exploit payloads, and never otherwise follow a request to create
+  malicious software. If asked, refuse and suggest a safe, defensive framing.
+- Mechanical guardrails additionally enforce this: destructive shell commands are
+  blocked before execution, file writes are scanned for malware indicators, and
+  flagged output is scrubbed from history. If a tool returns a "Guardrail blocked"
+  message, that means your proposed action was refused by policy — choose a safer
+  alternative and explain the refusal to the user.
+"""
+
+
+class AgentState(TypedDict):
+    messages: Annotated[list, add_messages]
+
+
+def build_graph(tools: list, model_override: str = None):
+    """tools: the combined list of local tools (bash, read_file, etc.) and
+    any MCP-provided tools (e.g. git) — assembled by main.py before this
+    is called, since loading MCP tools is async.
+
+    model_override: pass a model ID to use instead of whatever llm.py
+    defaults to. Requires get_llm() in your llm.py to accept an optional
+    override argument — see the note in main.py's /model command if it
+    doesn't yet."""
+    llm_with_tools = get_llm(model_override).bind_tools(tools)
+
+    def call_model(state: AgentState):
+        response = llm_with_tools.invoke(state["messages"])
+        return {"messages": [response]}
+
+    graph = StateGraph(AgentState)
+    graph.add_node("agent", call_model)
+    graph.add_node("tools", ToolNode(tools))
+    graph.set_entry_point("agent")
+    graph.add_conditional_edges("agent", tools_condition)
+    graph.add_edge("tools", "agent")
+    return graph.compile()

closecode_ai-0.1.0/closecode_ai.egg-info/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: closecode-ai
+Version: 0.1.0
+Summary: CloseCode — an agentic terminal coding assistant (LangGraph + OpenRouter + MCP)
+Author: Om Gite
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: langchain
+Requires-Dist: langgraph
+Requires-Dist: langchain-huggingface
+Requires-Dist: langsmith
+Requires-Dist: huggingface_hub
+Requires-Dist: python-dotenv
+Requires-Dist: requests
+Requires-Dist: langchain-openai
+Requires-Dist: langchain-mcp-adapters
+Requires-Dist: mcp-server-git
+Requires-Dist: langchain-openrouter
+Requires-Dist: rich
+Requires-Dist: pyfiglet
+
+# terminal-agent
+
+A minimal terminal coding agent built with LangGraph (agent loop), LangChain
+(tool + model abstraction), LangSmith (tracing), and a Hugging Face model as
+the LLM. Same shape as OpenCode/Terminus 2: read task -> decide -> run tool ->
+observe result -> repeat.
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+cp .env.example .env
+```
+
+Edit `.env`:
+- `HUGGINGFACEHUB_API_TOKEN` — from https://huggingface.co/settings/tokens
+- `HF_MODEL_ID` — a model that supports tool/function calling (see note below)
+- `LANGCHAIN_API_KEY` — optional, from https://smith.langchain.com, enables tracing
+
+## Run
+
+```bash
+python main.py
+```
+
+If `OPENROUTER_API_KEY` isn't set (env or `.env`), the agent prompts you to
+paste one at startup — input is hidden — and offers to save it to `.env`
+for next time. You can rotate it later with the `/key` command.
+
+## Switching models
+
+```text
+/models            list all OpenRouter models (● = current, free first)
+/models qwen       filter the list by name
+/models --refresh  force a fresh fetch (list is cached for 24h)
+/model 12          switch by list number
+/model qwen/qwen-2.5-72b-instruct   or any OpenRouter model id directly
+```
+
+The list comes live from OpenRouter's API and is cached for 24 hours in
+`~/.cache/closecode/`; if you're offline it falls back to a curated
+shortlist. The model choice is saved per session, so `/resume` restores
+the model you were using. Free-tier `:free` models cost nothing; check
+https://openrouter.ai/models for paid-model pricing before switching.
+
+The agent operates inside `./sandbox` (configurable via `AGENT_WORKDIR`) and
+will ask for permission before running shell commands or writing files,
+unless `AGENT_AUTO_APPROVE=true`.
+
+## Persistent sessions (SQLite)
+
+Conversations are stored in `./sessions/sessions.db` as per-message rows plus
+session metadata (name, model, mode, created/updated timestamps, message
+count). Existing `session_*.json` files are auto-migrated into the DB on the
+first run.
+
+- `--continue` — resume the most recently used session (its mode/model are
+  restored from metadata).
+- `/sessions` — list all saved sessions with metadata.
+- `/resume <id>` — switch to a saved conversation.
+- `/delete <id>` — delete a saved session.
+- Each turn is saved automatically; a session's name is derived from its
+  first user message.
+
+## Guardrails
+
+The agent is scoped to coding only, and `guardrails.py` enforces that with
+four layers:
+
+1. **Input scope** — off-topic chatter (greetings, opinions, trivia, creative
+   writing, news takes) is redirected to a coding task, and clearly malicious
+   requests (keyloggers, account hacking, phishing kits) are refused before
+   they reach the model.
+2. **Command blocking** — destructive shells commands (`rm -rf /`, `mkfs`,
+   disk wipes, fork bombs, `curl | sh`, reverse shells) are blocked before
+   execution, *even when auto-approve is on*.
+3. **Write scanning** — file writes/edits containing malware indicators
+   (ransomware, keyloggers, miners, persistence, injection) are refused.
+4. **Output redaction** — the model's final answer is scanned and flagged
+   content is scrubbed from conversation history.
+
+These are conservative heuristics on top of the sandbox + per-action
+permission prompts, not a hard guarantee. Set `AGENT_DISABLE_GUARDRAILS=true`
+in `.env` to disable them entirely (only for trusted, isolated testing).
+
+## A note on model choice
+
+Tool-calling reliability varies significantly across open Hugging Face
+models — this is the single biggest factor in whether this agent actually
+works well. Frontier closed models (what Claude Code / OpenCode use by
+default) are heavily trained specifically for reliable tool use; open models
+are improving but inconsistent.
+
+Models worth trying, roughly in order of tool-calling reliability:
+- `Qwen/Qwen2.5-72B-Instruct`
+- `meta-llama/Meta-Llama-3.1-70B-Instruct`
+- `meta-llama/Meta-Llama-3.1-8B-Instruct` (fastest/cheapest, least reliable)
+
+If a smaller model frequently fails to call tools correctly, or hallucinates
+tool arguments, that's expected — it's a real, documented gap between open
+and closed models on agentic tasks, not a bug in this code. Swapping
+`HF_MODEL_ID` is the first thing to try before changing anything else.
+
+## Where to go next
+
+1. **Watch a trace in LangSmith** (smith.langchain.com) once you have a run —
+   seeing the exact messages/tool calls at each step is the fastest way to
+   debug why the agent did something unexpected.
+2. **Add more tools** — `list_dir`, `edit_file` (targeted find/replace instead
+   of full overwrite), `run_tests`.
+3. **Split client/server** — move `build_graph()` behind a small FastAPI/
+   WebSocket server, and make `main.py` a thin client that streams from it.
+   This is the step that makes it architecturally closer to OpenCode.
+4. **Swap the sandbox for Docker** — the current harness restricts file paths
+   but shell commands still run on your actual machine. For anything beyond
+   personal experimentation, run `bash` calls inside a container instead.

closecode_ai-0.1.0/closecode_ai.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+README.md
+agent.py
+debug_response.py
+guardrails.py
+harness.py
+llm.py
+main.py
+mcp_tools.py
+modes.py
+pyproject.toml
+search.py
+session.py
+todos.py
+token_tracker.py
+tools.py
+ui.py
+closecode_ai.egg-info/PKG-INFO
+closecode_ai.egg-info/SOURCES.txt
+closecode_ai.egg-info/dependency_links.txt
+closecode_ai.egg-info/entry_points.txt
+closecode_ai.egg-info/requires.txt
+closecode_ai.egg-info/top_level.txt

closecode_ai-0.1.0/closecode_ai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

closecode_ai-0.1.0/closecode_ai.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+closecode = main:cli_entry

closecode_ai-0.1.0/closecode_ai.egg-info/requires.txt

@@ -0,0 +1,13 @@
+langchain
+langgraph
+langchain-huggingface
+langsmith
+huggingface_hub
+python-dotenv
+requests
+langchain-openai
+langchain-mcp-adapters
+mcp-server-git
+langchain-openrouter
+rich
+pyfiglet

closecode_ai-0.1.0/closecode_ai.egg-info/top_level.txt

@@ -0,0 +1,14 @@
+agent
+debug_response
+guardrails
+harness
+llm
+main
+mcp_tools
+modes
+search
+session
+todos
+token_tracker
+tools
+ui

closecode_ai-0.1.0/debug_response.py

@@ -0,0 +1,25 @@
+
+import os
+from dotenv import load_dotenv
+load_dotenv()
+
+from llm import get_llm
+from tools import LOCAL_TOOLS
+from langchain_core.messages import HumanMessage, SystemMessage
+from agent import SYSTEM_PROMPT
+
+llm = get_llm().bind_tools(LOCAL_TOOLS)
+messages = [
+    SystemMessage(content=SYSTEM_PROMPT),
+    HumanMessage(content='add a third line to output.txt that says "done"'),
+]
+response = llm.invoke(messages)
+
+print("=== content ===")
+print(repr(response.content))
+print("\n=== tool_calls ===")
+print(response.tool_calls)
+print("\n=== additional_kwargs ===")
+print(response.additional_kwargs)
+print("\n=== response_metadata ===")
+print(response.response_metadata)