lite-cc 0.1.0__tar.gz

lite_cc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keyang Ru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lite_cc-0.1.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: lite-cc
+Version: 0.1.0
+Summary: Lightweight multi-model coding agent CLI
+Author-email: Keyang Ru <rukeyang@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/key4ng/lite-cc
+Project-URL: Repository, https://github.com/key4ng/lite-cc
+Keywords: llm,agent,cli,coding-agent,litellm,multi-model
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: litellm>=1.40
+Requires-Dist: oci>=2.0
+Requires-Dist: pyyaml>=6.0
+Dynamic: license-file
+
+<p align="center">
+  <h1 align="center">lite-cc</h1>
+  <p align="center">
+    A minimal, multi-model coding agent runtime for the terminal.
+  </p>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> &middot;
+  <a href="#how-it-works">How It Works</a> &middot;
+  <a href="#plugins--skills">Plugins & Skills</a> &middot;
+  <a href="#configuration">Configuration</a> &middot;
+  <a href="#safety">Safety</a>
+</p>
+
+---
+
+<p align="center">
+  <img src="assets/demo.gif" alt="litecc demo" width="720">
+</p>
+
+**lite-cc** (`litecc`) is a lightweight, provider-agnostic coding agent for the terminal. It connects to any LLM via [LiteLLM](https://docs.litellm.ai/docs/providers), runs an autonomous tool loop, and extends its capabilities through plugins and skills.
+
+## Key Features
+
+- **Multi-model** — OpenAI, Anthropic, OCI, Gemini, Groq, Ollama, and [any provider LiteLLM supports](https://docs.litellm.ai/docs/providers).
+- **Autonomous tool loop** — Reasons, calls tools, observes results, and iterates until the task is done.
+- **Plugin & skill system** — Load plugins to inject domain knowledge. Skills are loaded on demand to keep context lean.
+- **Safe by default** — Dangerous commands are blocked. File access is scoped to the project directory. Fully autonomous, no prompts.
+- **Structured output** — Colored, timestamped progress logs show exactly what the agent is doing.
+
+## Quick Start
+
+```bash
+# Install
+git clone https://github.com/key4ng/lite-cc.git
+cd lite-cc
+pip install -e .
+
+# Run
+litecc run "list all Python files and describe what each one does"
+
+# Run with the example plugin
+litecc run "analyze cc/agent.py" --plugin-dir examples/code-analyst
+```
+
+Output:
+
+```
+14:32:05 [litecc]  Using model: gpt-5.2
+14:32:05 [litecc]  Starting task...
+14:32:06 [tool]    list_files: **/*.py
+14:32:07 [tool]    read_file: cc/agent.py
+14:32:08 [gpt-5.2] I'll describe each file...
+14:32:09 [litecc]  Here are the Python files...
+```
+
+## How It Works
+
+```
+litecc run "fix the failing tests"
+        │
+        ▼
+  Load config, plugins, skills
+        │
+        ▼
+  Build system prompt + tool definitions
+        │
+        ▼
+  ┌─ Agent Loop ──────────────────────────┐
+  │  1. Send messages + tools to LLM      │
+  │  2. LLM returns tool calls            │
+  │     → execute safely → append results │
+  │  3. LLM returns text → done           │
+  └───────────────────────────────────────┘
+```
+
+The loop runs until the model produces a final answer or hits the max iteration limit.
+
+## Usage
+
+```bash
+# Basic task
+litecc run "fix the failing tests"
+
+# Choose a model
+litecc run "refactor this module" --model anthropic/claude-3-sonnet-20240229
+
+# Load plugins
+litecc run "triage the latest ticket" --plugin-dir ~/my-plugin
+litecc run "check health" --plugin-dir ~/plugin-a --plugin-dir ~/plugin-b
+
+# Different project directory
+litecc run "explain the architecture" --project-dir ~/other-repo
+
+# Verbose output (show tool results, full reasoning)
+litecc run "explore the codebase" -v
+
+# Limit iterations
+litecc run "explore the codebase" --max-iterations 20
+```
+
+<details>
+<summary>CLI Reference</summary>
+
+```
+Usage: litecc run [OPTIONS] PROMPT
+
+Options:
+  --plugin-dir TEXT      Plugin directory (repeatable)
+  --model TEXT           LiteLLM model string
+  --max-iterations INT   Max tool loop iterations (default: 50)
+  --project-dir TEXT     Working directory (default: cwd)
+  -v, --verbose          Show detailed tool output
+  --help                 Show this message and exit
+```
+
+</details>
+
+## Plugins & Skills
+
+lite-cc uses a plugin format compatible with Claude Code. Plugins provide domain knowledge and reusable workflows.
+
+### Plugin Structure
+
+```
+my-plugin/
+  .claude-plugin/
+    plugin.json          # Manifest (required)
+  CLAUDE.md              # Instructions injected into system prompt
+  pipeline/
+    deploy-check/
+      SKILL.md           # Skill with YAML frontmatter
+  commands/
+    triage.md            # Command-style skill
+```
+
+### Skill Format
+
+```markdown
+---
+name: deploy-check
+description: Verify a deployment is healthy by checking pod status and logs.
+---
+
+# Deploy Check
+
+## Steps
+
+1. Check pod status:
+   ﹩bash
+   kubectl get pods -n <NAMESPACE> -o wide
+   ﹩
+
+2. Review recent events and summarize findings.
+```
+
+### How It Works
+
+1. On startup, `--plugin-dir` directories are scanned for `.claude-plugin/plugin.json`
+2. `CLAUDE.md` is injected into the system prompt
+3. Skills are indexed by name and description — the model sees the list but not the full content
+4. When needed, the model calls `use_skill("deploy-check")` to load the full instructions
+5. The skill content is injected into the conversation and the model follows the steps
+
+This keeps context lean — only the skills actually needed are loaded.
+
+## Configuration
+
+Config is resolved in order of precedence (highest wins):
+
+| Priority | Source | Example |
+|----------|--------|---------|
+| 1 | CLI flags | `--model openai/gpt-4o` |
+| 2 | Environment variables | `CC_MODEL=openai/gpt-4o` |
+| 3 | Config file | `~/.cc/config.yaml` |
+| 4 | Defaults | `oci/openai.gpt-5.2` |
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CC_MODEL` | `oci/openai.gpt-5.2` | LiteLLM model identifier |
+| `CC_OCI_REGION` | `us-chicago-1` | OCI region for inference |
+| `CC_OCI_COMPARTMENT` | — | OCI compartment OCID (required for `oci/` models) |
+| `CC_OCI_CONFIG_PROFILE` | `DEFAULT` | OCI config profile |
+| `CC_MAX_ITERATIONS` | `50` | Max agent loop iterations |
+| `CC_TIMEOUT` | `120` | Per-command timeout (seconds) |
+
+<details>
+<summary>YAML config example</summary>
+
+Create `~/.cc/config.yaml`:
+
+```yaml
+model: oci/openai.gpt-5.2
+oci_region: us-chicago-1
+oci_compartment: ocid1.tenancy.oc1..aaaaaaaexample
+max_iterations: 50
+timeout: 120
+```
+
+</details>
+
+### Supported Models
+
+Any [LiteLLM provider](https://docs.litellm.ai/docs/providers) works out of the box:
+
+| Provider | Model Example | Auth |
+|----------|--------------|------|
+| OpenAI | `openai/gpt-4o` | `OPENAI_API_KEY` |
+| Anthropic | `anthropic/claude-3-sonnet-20240229` | `ANTHROPIC_API_KEY` |
+| OCI GenAI | `oci/openai.gpt-5.2` | `~/.oci/config` session token |
+| Gemini | `gemini/gemini-pro` | `GEMINI_API_KEY` |
+| Groq | `groq/llama3-70b-8192` | `GROQ_API_KEY` |
+| Ollama | `ollama/llama3` | Local server |
+
+## Built-in Tools
+
+| Tool | Description |
+|------|-------------|
+| `bash` | Shell execution with safety checks, output truncation, and timeout |
+| `read_file` | Read files with optional line range (`offset`, `limit`) |
+| `write_file` | Create or overwrite files (auto-creates parent dirs) |
+| `list_files` | Glob pattern search (e.g., `**/*.py`) |
+| `grep` | Recursive regex search across files |
+| `use_skill` | Load a skill's instructions into the conversation |
+
+All file tools are scoped to the project directory. Bash commands are checked against a deny list before execution.
+
+## Safety
+
+lite-cc enforces safety guardrails at the tool execution layer — no user prompts, just deny and report.
+
+### Blocked Commands
+
+| Category | Patterns |
+|----------|----------|
+| File deletion | `rm`, `rmdir`, `unlink` |
+| Privilege escalation | `sudo`, `su`, `doas` |
+| System control | `shutdown`, `reboot`, `halt` |
+| Disk operations | `mkfs`, `fdisk`, `dd` |
+| Process control | `kill`, `killall`, `pkill` |
+| Destructive git | `git push --force`, `git clean` |
+| Remote code exec | `curl ... \| sh`, `wget ... \| bash` |
+
+### Path Restrictions
+
+- All file operations resolve inside the project directory
+- Path traversal (`../../etc/passwd`) is detected and blocked
+- Sensitive paths blocked: `~/.ssh`, `~/.aws`, `/etc`, `/private`
+
+### Output Limits
+
+- **2000 lines** or **100KB** per command (whichever is first)
+- **120s** timeout (configurable via `CC_TIMEOUT`)
+
+> The safety layer is a guardrail, not a security boundary. It prevents common destructive operations in an autonomous loop.
+
+## Architecture
+
+```
+cc/
+  cli.py              # Click CLI entry point
+  config.py           # Layered config (CLI > env > yaml > defaults)
+  agent.py            # Core tool loop with progress logging
+  llm.py              # LiteLLM wrapper with OCI auth
+  safety.py           # Command deny list + path checks
+  output.py           # Colored terminal output
+  tools/              # Built-in tool implementations
+  plugins/            # Plugin discovery + skill indexing
+```
+
+## Development
+
+```bash
+pip install -e .        # Install
+pytest -v               # Run all 35 tests
+pytest -k "safety" -v   # Run tests by pattern
+```
+
+## License
+
+MIT

lite_cc-0.1.0/README.md

@@ -0,0 +1,284 @@
+<p align="center">
+  <h1 align="center">lite-cc</h1>
+  <p align="center">
+    A minimal, multi-model coding agent runtime for the terminal.
+  </p>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> &middot;
+  <a href="#how-it-works">How It Works</a> &middot;
+  <a href="#plugins--skills">Plugins & Skills</a> &middot;
+  <a href="#configuration">Configuration</a> &middot;
+  <a href="#safety">Safety</a>
+</p>
+
+---
+
+<p align="center">
+  <img src="assets/demo.gif" alt="litecc demo" width="720">
+</p>
+
+**lite-cc** (`litecc`) is a lightweight, provider-agnostic coding agent for the terminal. It connects to any LLM via [LiteLLM](https://docs.litellm.ai/docs/providers), runs an autonomous tool loop, and extends its capabilities through plugins and skills.
+
+## Key Features
+
+- **Multi-model** — OpenAI, Anthropic, OCI, Gemini, Groq, Ollama, and [any provider LiteLLM supports](https://docs.litellm.ai/docs/providers).
+- **Autonomous tool loop** — Reasons, calls tools, observes results, and iterates until the task is done.
+- **Plugin & skill system** — Load plugins to inject domain knowledge. Skills are loaded on demand to keep context lean.
+- **Safe by default** — Dangerous commands are blocked. File access is scoped to the project directory. Fully autonomous, no prompts.
+- **Structured output** — Colored, timestamped progress logs show exactly what the agent is doing.
+
+## Quick Start
+
+```bash
+# Install
+git clone https://github.com/key4ng/lite-cc.git
+cd lite-cc
+pip install -e .
+
+# Run
+litecc run "list all Python files and describe what each one does"
+
+# Run with the example plugin
+litecc run "analyze cc/agent.py" --plugin-dir examples/code-analyst
+```
+
+Output:
+
+```
+14:32:05 [litecc]  Using model: gpt-5.2
+14:32:05 [litecc]  Starting task...
+14:32:06 [tool]    list_files: **/*.py
+14:32:07 [tool]    read_file: cc/agent.py
+14:32:08 [gpt-5.2] I'll describe each file...
+14:32:09 [litecc]  Here are the Python files...
+```
+
+## How It Works
+
+```
+litecc run "fix the failing tests"
+        │
+        ▼
+  Load config, plugins, skills
+        │
+        ▼
+  Build system prompt + tool definitions
+        │
+        ▼
+  ┌─ Agent Loop ──────────────────────────┐
+  │  1. Send messages + tools to LLM      │
+  │  2. LLM returns tool calls            │
+  │     → execute safely → append results │
+  │  3. LLM returns text → done           │
+  └───────────────────────────────────────┘
+```
+
+The loop runs until the model produces a final answer or hits the max iteration limit.
+
+## Usage
+
+```bash
+# Basic task
+litecc run "fix the failing tests"
+
+# Choose a model
+litecc run "refactor this module" --model anthropic/claude-3-sonnet-20240229
+
+# Load plugins
+litecc run "triage the latest ticket" --plugin-dir ~/my-plugin
+litecc run "check health" --plugin-dir ~/plugin-a --plugin-dir ~/plugin-b
+
+# Different project directory
+litecc run "explain the architecture" --project-dir ~/other-repo
+
+# Verbose output (show tool results, full reasoning)
+litecc run "explore the codebase" -v
+
+# Limit iterations
+litecc run "explore the codebase" --max-iterations 20
+```
+
+<details>
+<summary>CLI Reference</summary>
+
+```
+Usage: litecc run [OPTIONS] PROMPT
+
+Options:
+  --plugin-dir TEXT      Plugin directory (repeatable)
+  --model TEXT           LiteLLM model string
+  --max-iterations INT   Max tool loop iterations (default: 50)
+  --project-dir TEXT     Working directory (default: cwd)
+  -v, --verbose          Show detailed tool output
+  --help                 Show this message and exit
+```
+
+</details>
+
+## Plugins & Skills
+
+lite-cc uses a plugin format compatible with Claude Code. Plugins provide domain knowledge and reusable workflows.
+
+### Plugin Structure
+
+```
+my-plugin/
+  .claude-plugin/
+    plugin.json          # Manifest (required)
+  CLAUDE.md              # Instructions injected into system prompt
+  pipeline/
+    deploy-check/
+      SKILL.md           # Skill with YAML frontmatter
+  commands/
+    triage.md            # Command-style skill
+```
+
+### Skill Format
+
+```markdown
+---
+name: deploy-check
+description: Verify a deployment is healthy by checking pod status and logs.
+---
+
+# Deploy Check
+
+## Steps
+
+1. Check pod status:
+   ﹩bash
+   kubectl get pods -n <NAMESPACE> -o wide
+   ﹩
+
+2. Review recent events and summarize findings.
+```
+
+### How It Works
+
+1. On startup, `--plugin-dir` directories are scanned for `.claude-plugin/plugin.json`
+2. `CLAUDE.md` is injected into the system prompt
+3. Skills are indexed by name and description — the model sees the list but not the full content
+4. When needed, the model calls `use_skill("deploy-check")` to load the full instructions
+5. The skill content is injected into the conversation and the model follows the steps
+
+This keeps context lean — only the skills actually needed are loaded.
+
+## Configuration
+
+Config is resolved in order of precedence (highest wins):
+
+| Priority | Source | Example |
+|----------|--------|---------|
+| 1 | CLI flags | `--model openai/gpt-4o` |
+| 2 | Environment variables | `CC_MODEL=openai/gpt-4o` |
+| 3 | Config file | `~/.cc/config.yaml` |
+| 4 | Defaults | `oci/openai.gpt-5.2` |
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CC_MODEL` | `oci/openai.gpt-5.2` | LiteLLM model identifier |
+| `CC_OCI_REGION` | `us-chicago-1` | OCI region for inference |
+| `CC_OCI_COMPARTMENT` | — | OCI compartment OCID (required for `oci/` models) |
+| `CC_OCI_CONFIG_PROFILE` | `DEFAULT` | OCI config profile |
+| `CC_MAX_ITERATIONS` | `50` | Max agent loop iterations |
+| `CC_TIMEOUT` | `120` | Per-command timeout (seconds) |
+
+<details>
+<summary>YAML config example</summary>
+
+Create `~/.cc/config.yaml`:
+
+```yaml
+model: oci/openai.gpt-5.2
+oci_region: us-chicago-1
+oci_compartment: ocid1.tenancy.oc1..aaaaaaaexample
+max_iterations: 50
+timeout: 120
+```
+
+</details>
+
+### Supported Models
+
+Any [LiteLLM provider](https://docs.litellm.ai/docs/providers) works out of the box:
+
+| Provider | Model Example | Auth |
+|----------|--------------|------|
+| OpenAI | `openai/gpt-4o` | `OPENAI_API_KEY` |
+| Anthropic | `anthropic/claude-3-sonnet-20240229` | `ANTHROPIC_API_KEY` |
+| OCI GenAI | `oci/openai.gpt-5.2` | `~/.oci/config` session token |
+| Gemini | `gemini/gemini-pro` | `GEMINI_API_KEY` |
+| Groq | `groq/llama3-70b-8192` | `GROQ_API_KEY` |
+| Ollama | `ollama/llama3` | Local server |
+
+## Built-in Tools
+
+| Tool | Description |
+|------|-------------|
+| `bash` | Shell execution with safety checks, output truncation, and timeout |
+| `read_file` | Read files with optional line range (`offset`, `limit`) |
+| `write_file` | Create or overwrite files (auto-creates parent dirs) |
+| `list_files` | Glob pattern search (e.g., `**/*.py`) |
+| `grep` | Recursive regex search across files |
+| `use_skill` | Load a skill's instructions into the conversation |
+
+All file tools are scoped to the project directory. Bash commands are checked against a deny list before execution.
+
+## Safety
+
+lite-cc enforces safety guardrails at the tool execution layer — no user prompts, just deny and report.
+
+### Blocked Commands
+
+| Category | Patterns |
+|----------|----------|
+| File deletion | `rm`, `rmdir`, `unlink` |
+| Privilege escalation | `sudo`, `su`, `doas` |
+| System control | `shutdown`, `reboot`, `halt` |
+| Disk operations | `mkfs`, `fdisk`, `dd` |
+| Process control | `kill`, `killall`, `pkill` |
+| Destructive git | `git push --force`, `git clean` |
+| Remote code exec | `curl ... \| sh`, `wget ... \| bash` |
+
+### Path Restrictions
+
+- All file operations resolve inside the project directory
+- Path traversal (`../../etc/passwd`) is detected and blocked
+- Sensitive paths blocked: `~/.ssh`, `~/.aws`, `/etc`, `/private`
+
+### Output Limits
+
+- **2000 lines** or **100KB** per command (whichever is first)
+- **120s** timeout (configurable via `CC_TIMEOUT`)
+
+> The safety layer is a guardrail, not a security boundary. It prevents common destructive operations in an autonomous loop.
+
+## Architecture
+
+```
+cc/
+  cli.py              # Click CLI entry point
+  config.py           # Layered config (CLI > env > yaml > defaults)
+  agent.py            # Core tool loop with progress logging
+  llm.py              # LiteLLM wrapper with OCI auth
+  safety.py           # Command deny list + path checks
+  output.py           # Colored terminal output
+  tools/              # Built-in tool implementations
+  plugins/            # Plugin discovery + skill indexing
+```
+
+## Development
+
+```bash
+pip install -e .        # Install
+pytest -v               # Run all 35 tests
+pytest -k "safety" -v   # Run tests by pattern
+```
+
+## License
+
+MIT

lite_cc-0.1.0/cc/__init__.py

@@ -0,0 +1 @@
+"""lite-cc — lightweight multi-model coding agent CLI."""

lite_cc-0.1.0/cc/__main__.py

@@ -0,0 +1,4 @@
+from cc.cli import main
+
+if __name__ == "__main__":
+    main()