{"id":31644514,"url":"https://github.com/benapetr/clia","last_synced_at":"2026-05-16T08:01:28.680Z","repository":{"id":318072477,"uuid":"1069894122","full_name":"benapetr/clia","owner":"benapetr","description":"Simple stupid LLM based CLI Agent","archived":false,"fork":false,"pushed_at":"2025-10-04T21:08:40.000Z","size":54,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-04T23:25:59.524Z","etag":null,"topics":["agentic-ai","cli","llm","ollama","ollama-client"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benapetr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-04T20:42:49.000Z","updated_at":"2025-10-04T21:08:44.000Z","dependencies_parsed_at":"2025-10-04T23:26:07.229Z","dependency_job_id":"5ebd7a21-2259-4482-8422-9a25f4781df4","html_url":"https://github.com/benapetr/clia","commit_stats":null,"previous_names":["benapetr/clia"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/benapetr/clia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benapetr%2Fclia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benapetr%2Fclia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benapetr%2Fclia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benapetr%2Fclia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benapetr","download_url":"https://codeload.github.com/benapetr/clia/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benapetr%2Fclia/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278722768,"owners_count":26034461,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","cli","llm","ollama","ollama-client"],"created_at":"2025-10-07T04:53:36.121Z","updated_at":"2025-10-07T04:53:38.533Z","avatar_url":"https://github.com/benapetr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CLIA: Command Line Interface Agent\n\nAn interactive command-line interface that lets an LLM act as a tool-using agent. The assistant can stream responses in real time and invoke registered tools—such as running shell commands or fetching webpage text—to complete tasks autonomously. By default the CLI targets a local Ollama instance, but it can also connect to OpenAI or Mistral endpoints.\n\n## Requirements\n\n- Python 3.9+\n- `requests` Python package\n- `beautifulsoup4` Python package\n- `ddgs` Python package (required for DuckDuckGo search; optional if using Google only)\n- One of:\n  - Local Ollama server running on `http://localhost:11434` (default)\n  - OpenAI API access with a valid key\n  - Mistral API access with a valid key\n\n## Installation\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n```\n\n## Usage\n\nStart the agent with the default model (`llama3`):\n\n```bash\npython3 agent_cli.py\n```\n\nYou can provide an initial message and override model settings:\n\n```bash\npython3 agent_cli.py \"help me summarize this repo\" --model llama3.1 --temperature 0.2\n```\n\nUse `--shell-timeout` to adjust how long the `run_shell` tool may run (in seconds):\n\n```bash\npython3 agent_cli.py --shell-timeout 120\n```\n\nUse `--request-timeout` to set the request timeout for streaming responses:\n\n```bash\npython3 agent_cli.py --request-timeout 300\n```\n\nDisable colored prompts if your terminal does not support ANSI escape codes:\n\n```bash\npython3 agent_cli.py --no-color\n```\n\nOverride the configuration directory (default is `~/.config/clia`):\n\n```bash\npython3 agent_cli.py --config-dir ./tmp/config\n```\n\nSwitch providers from the command line:\n\n```bash\npython3 agent_cli.py --provider openai --model gpt-4o-mini --api-key \"$OPENAI_API_KEY\"\n```\n\n## Configuration\n\nWhen present, `~/.config/clia/config.ini` (override with `--config-dir`) supplies defaults:\n\n```ini\n[model]\nprovider = ollama           # or openai / mistral\nmodel = llama3\nendpoint = http://localhost:11434\napi_key =                   # required for openai/mistral\ntemperature = 0.7\ntimeout = 120\nsystem_prompt = prompts/system-prompt.txt\n\n[search]\nprovider = duckduckgo       # or google\napi_key =                   # required when provider = google\nengine_id =                 # Google Programmable Search Engine ID (cx)\n\n[storage]\nsessions_dir = ~/.config/clia/sessions\n\n[debug]\nlog_file = /tmp/clia.log\n\n[output]\ntruncation_limit = 4000\n\n[unsafe]\nenabled = off\n```\n\nCLI flags always take precedence over values loaded from `config.ini`. The endpoint should be the base URL for the provider (e.g., `https://api.openai.com/v1`).\n\nWhen `search.provider = google`, populate both `api_key` and `engine_id` with credentials for a Google Programmable Search Engine (Custom Search JSON API). DuckDuckGo requires no additional configuration.\nSet `storage.sessions_dir` to change where session files are stored; paths are expanded with `~` and may be absolute.\nDuckDuckGo searches depend on the optional `ddgs` package; install it alongside `requests` when using the default provider.\nSet `system_prompt` to the path of a template file (absolute or relative to the config directory). The template may include `{tools}`, `{tool_descriptions}`, or `{{tools}}` placeholders, which are replaced with the current tool list.\nAn example starter template lives at `docs/system-prompt-example.txt`.\nUse `[debug] log_file` to direct debug traces to a specific location (defaults to `/tmp/clia.log`).\nUse `[output] truncation_limit` to control how many characters tool outputs retain before truncation (default 4000).\nSystem prompts support placeholders like `{tools}`, `{date}`, and `{time}` for dynamic context.\n\n## Project Structure\n\n```\nagent_cli.py        # CLI entrypoint and argument parsing\nclia/\n  cli.py            # Conversation loop, streaming, and tool orchestration\n  clients.py        # HTTP clients for Ollama, OpenAI, and Mistral\n  commands/         # Slash-command framework and default command handlers\n  ollama.py         # Compatibility shim re-exporting the Ollama client\n  approval.py       # Tool approval persistence and prompts\n  tooling.py        # Tool dataclass and registry implementation\n  utils.py          # Shared helpers (HTML stripping, truncation)\n  tools/\n    run_shell.py    # Shell command execution tool\n    read_url.py     # URL fetch/strip tool\n    search_internet.py  # Configurable internet search tool\n```\n\nWhile the program is running:\n\n- Type your prompts after the `you\u003e` prompt (shown in yellow when the terminal supports color, or plain if `--no-color` is used).\n- Enter `exit` or press `Ctrl+D` to quit.\n- When the model decides to use a tool, the CLI displays the call and its result before continuing the chat; agent output is prefixed with a cyan `agent\u003e` label (plain when `--no-color` is active).\n- For models that emit `\u003cthink\u003e...\u003c/think\u003e` meta tags, the content inside the tags is rendered in light gray to distinguish reasoning from the final answer (colorized output only).\n- System commands start with `/` and are handled locally:\n  - `/help` – list available commands\n  - `/info` – show provider/model and an approximate session token count\n  - `/save \u003cname|path\u003e` – save the current dialogue to the configured sessions directory or a specific path\n  - `/load \u003cname|path\u003e` – restore a saved dialogue from the configured directory or an explicit path\n  - `/ls` – list saved session files in the configured directory\n  - `/rm \u003cname|path\u003e` – delete a saved session file\n  - `/tail [N]` – print the last `N` conversation messages (default 5)\n  - `/truncate on|off` – enable or disable tool output truncation globally\n  - `/debug [on|off]` – toggle or display debug logging status (writes to the debug log file)\n  - `/debug_tool \u003ctool\u003e \u003cjson\u003e` – run a tool manually for debugging\n    Example: `/debug_tool search_internet \\\"{\\\\\"query\\\\\": \\\\\"format input data for fine tuning mistral model\\\\\"}\\\"`\n             `/debug_tool run_shell \\\"{\\\\\"command\\\\\": \\\\\"ls\\\\\"}\\\"`\n  - `/exit` – exit immediately\n\n## Tool Approval Workflow\n\n- On startup, the agent reads a list of auto-approved tools from `allowed_tools` inside the configuration directory (default `~/.config/clia/allowed_tools`).\n- When the model requests a tool that is not on the approved list, the CLI prompts you to allow it once (`y`), deny it (`n`), or always allow it (`a`).\n- Choosing `a` adds the tool to the in-memory allowlist and appends it to `allowed_tools`, creating the file if necessary.\n\n## Tooling\n\nTools registered by default:\n\n| Tool | Description | Arguments |\n|------|-------------|-----------|\n| `run_shell` | Execute shell commands inside the project workspace (timeout configurable via `--shell-timeout`). | `{ \"command\": \"\u003cshell command string\u003e\" }` |\n| `read_url` | Fetch webpage text, preserve links, and return a trimmed plain-text summary. | `{ \"url\": \"https://example.com\" }` |\n| `search_internet` | Query the configured search provider (DuckDuckGo or Google PSE). | `{ \"query\": \"open source llm agents\" }` |\n| `bc` | Evaluate math expressions via the system `bc -l` calculator. | `{ \"expression\": \"(2 + 2) * 3\" }` |\n| `file_edit` | Modify files by writing, appending, or inserting text content. | `{ \"path\": \"notes.txt\", \"mode\": \"append\", \"content\": \"More text\" }` |\n\nYou can add more tools by extending `clia/tools/__init__.py`.\n\n## Development\n\nCheck that the script compiles:\n\n```bash\npython3 -m compileall agent_cli.py\n```\n\nConsider adding automated tests or linting as the project grows.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenapetr%2Fclia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenapetr%2Fclia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenapetr%2Fclia/lists"}