Metadata-Version: 2.4
Name: joshu
Version: 0.3.0
Summary: A coding agent for the terminal that works with any OpenAI-compatible model
Author: Joshu Community
License: MIT License
        
        Copyright (c) 2025 FAYCAL RAGHIBI
        
        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.
        
Project-URL: Homepage, https://github.com/Faycalraghibi/Joshu
Project-URL: Documentation, https://github.com/Faycalraghibi/Joshu/tree/main/docs
Project-URL: Changelog, https://github.com/Faycalraghibi/Joshu/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Faycalraghibi/Joshu/issues
Keywords: cli,ai,agent,coding-agent,llm,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.54.0
Requires-Dist: typer==0.20.0
Requires-Dist: rich==14.2.0
Requires-Dist: pydantic==2.12.3
Requires-Dist: python-dotenv==1.2.1
Requires-Dist: prompt_toolkit==3.0.52
Requires-Dist: requests==2.32.5
Requires-Dist: tqdm==4.67.1
Requires-Dist: PyYAML==6.0.3
Requires-Dist: ddgs>=9.0.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest==8.4.2; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: black==24.4.0; extra == "dev"
Requires-Dist: flake8==7.0.0; extra == "dev"
Requires-Dist: mypy==1.8.0; extra == "dev"
Requires-Dist: ruff==0.2.0; extra == "dev"
Requires-Dist: isort==5.13.2; extra == "dev"
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Requires-Dist: types-PyYAML==6.0.12.12; extra == "dev"
Requires-Dist: types-requests>=2.31.0; extra == "dev"
Requires-Dist: fastapi>=0.110.0; extra == "dev"
Provides-Extra: a2a
Requires-Dist: fastapi>=0.110.0; extra == "a2a"
Requires-Dist: uvicorn>=0.29.0; extra == "a2a"
Provides-Extra: use
Requires-Dist: chromadb>=0.4.0; extra == "use"
Requires-Dist: sentence-transformers>=2.2.0; extra == "use"
Dynamic: license-file

# Joshu

A coding agent for your terminal. Describe a task in plain language and Joshu
reads and searches your code, edits files and runs commands until it's done,
asking before anything risky. It works with any OpenAI-compatible model
provider, including free and local models.

```bash
joshu "add a --verbose flag to the CLI and update the tests"
```

## Features

- **Agent loop**: the model uses tools (read, search, edit, shell, web,
  sub-agents, MCP servers), sees the results and keeps going until the task is
  done; independent reads and sub-agents run in parallel
- **Permissions and safety**: edits show a diff and commands ask first;
  `accept_edits`, read-only `plan` and `bypass` modes; `.env` files, keys and
  credentials need explicit approval and secrets are masked in tool output
- **Any provider**: NVIDIA, OpenRouter, OpenAI, Anthropic, Gemini, Groq,
  Mistral, DeepSeek, Ollama, LM Studio, vLLM or any OpenAI-compatible endpoint;
  live model lists, named models, retries and fallback models
- **Code intelligence**: language-server errors after every edit, plus
  go-to-definition, references and hover
- **Interactive mode**: themes, a `/` command menu with ~50 commands, Esc to
  interrupt, `/rewind`, `/compact`, `/init`, skills and memory across sessions
- **Lean on tokens**: on-demand tool loading, compact results and context
  clearing keep a plain "hi" around 2k tokens
- **Extensible**: custom commands, sub-agents, skills, hooks, MCP tools,
  prompts and resources, output styles
- **Programmable**: a Python SDK, JSON / streaming JSON output, an HTTP server
  (`joshu serve`) and a GitHub Action that works on `@joshu` comments

## Install

Python 3.10 or newer.

```bash
pipx install joshu        # or: pip install joshu
```

From source: `git clone https://github.com/Faycalraghibi/Joshu.git && cd Joshu && pip install -e .`
(add `[use]` for semantic memory, `[a2a]` for the HTTP server).

## Set up a model

The default is NVIDIA's free Nemotron 3.5 Lightning. Get a free key at
[build.nvidia.com](https://build.nvidia.com) and put it in `.env` or your
environment:

```bash
NVIDIA_API_KEY=nvapi-...
```

Check the setup with `joshu` then `/doctor`. To use something else:

```bash
joshu providers                                   # providers and key status
joshu models -p openrouter --tools --free         # browse a provider's models
joshu use qwen3-coder -p ollama                   # local models, no key needed
```

## Use

```bash
joshu                                         # interactive (/help, ? for shortcuts)
joshu "why does test_login fail?"             # one task
joshu run --permission-mode plan "how is auth implemented?"   # read-only
joshu run -p --output-format json "list the TODOs"            # for scripts
joshu run --continue "now add tests for it"   # continue the last conversation
```

From Python:

```python
from joshu import run
print(run("summarize README.md").text)
```

## Documentation

- [Quick start](docs/quick-start.md)
- [Agent: permissions, tools, memory, skills, sandbox](docs/agent.md)
- [Interactive mode and slash commands](docs/interactive-mode.md)
- [Models & providers](docs/models-and-providers.md)
- [Python SDK and streaming](docs/sdk.md)
- [GitHub Action](docs/github-action.md)
- [Hooks](docs/hooks.md) · [MCP servers](docs/mcp-servers.md) · [Configuration](docs/configuration.md)
- [Roadmap](docs/roadmap.md) · [All documentation](docs/README.md)

## License

MIT
