# maxs
**Build AI tools while talking to them**
Stop writing configs. Stop restarting servers. Just speak:
*"max, create a tool that monitors our Kubernetes cluster"*
→ Tool created, tested, and running in 30 seconds
## 🚀 Try it now (2 minutes)
```bash
pipx install maxs && maxs
```
Then just speak:
- *"max, what time is it?"* → Instant response
- *"max, create a weather tool"* → Tool appears in ./tools/
- *"max, use the weather tool for Tokyo"* → Working immediately
**No configuration. No API keys. No YAML files.**
## 💡 How it works
```
Voice Command → Hot Reload Tool Creation → Instant Usage
↓ ↓ ↓
"max, create X" ./tools/X.py saved Tool ready to use
```
**Three revolutionary features:**
🎙️ **Voice-First Development** - Build tools by talking
🔥 **Instant Hot Reload** - Tools work immediately, no restart
📡 **P2P Agent Network** - Agents communicate over encrypted mesh
## ⚡ Setup (choose one)
**Option 1: Local AI (recommended for privacy)**
```bash
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull qwen3:4b
maxs
```
**Option 2: Cloud AI (recommended for power)**
```bash
# Anthropic Claude (best for development)
export ANTHROPIC_API_KEY="your-key"
MODEL_PROVIDER=anthropic maxs
# OpenAI GPT (good for general tasks)
export OPENAI_API_KEY="your-key"
MODEL_PROVIDER=openai maxs
# Other: bedrock, github, litellm, llamaapi, mistral
```
## 🔥 Key Features
### 🎙️ **Voice-Powered Development**
```bash
maxs
> listen(action="start", trigger_keyword="max")
# Then just speak naturally:
"max, analyze the server logs" → Creates monitoring tools
"max, deploy to staging" → Runs deployment scripts
"max, create a backup system" → Builds automation instantly
```
### 🔄 **Instant Hot Reload**
Create tools while maxs is running:
```python
# Save this to ./tools/weather.py
from strands import tool
@tool
def weather(city: str) -> str:
return f"Weather for {city}: 72°F, sunny"
```
Then immediately use it:
```bash
maxs "get weather for Tokyo" # Tool works instantly!
```
### 📡 **P2P Agent Network**
Agents communicate over encrypted Bluetooth mesh:
```bash
# Agent Alice says:
"max, analyze the server performance"
# Agent Bob automatically responds:
"Performance analysis complete. CPU at 85%, recommend scaling."
# No internet required - direct agent-to-agent communication
```
### 🧠 **Intelligent Memory**
Remembers everything across sessions:
```bash
maxs "remember: we're using PostgreSQL for user data"
# Later...
maxs "create a user analytics tool" # Uses PostgreSQL context
```
## 🛠️ Common Workflows
### Development & Automation
```bash
maxs "analyze this codebase and suggest improvements"
maxs "create deployment script for our Docker app"
maxs "monitor system logs in the background"
maxs "format all Python files in this project"
```
### Data Analysis
```bash
maxs "connect to PostgreSQL and analyze user growth"
maxs "create charts from the sales CSV file"
maxs "query the API and generate a report"
```
### Voice Control (Hands-Free)
```bash
# Start voice mode first
maxs
> listen(action="start", trigger_keyword="max")
# Then just speak:
"max, what's the system status?"
"max, backup the database"
"max, check for security updates"
```
## 🧰 Built-in Tools (50+)
<details>
<summary><strong>🎯 Essential Tools</strong> - Core functionality</summary>
| Tool | Purpose | Example |
|------|---------|---------|
| **shell** | Execute commands with real-time output | `check disk usage` |
| **editor** | File editing with syntax highlighting | `modify config files` |
| **python_repl** | Interactive Python execution | `run data analysis scripts` |
| **http_request** | Universal HTTP client | `call any REST API` |
</details>
<details>
<summary><strong>🎙️ Voice & Audio</strong> - Speech interaction</summary>
| Tool | Purpose | Example |
|------|---------|---------|
| **listen** | Speech-to-text with trigger keywords | `"max, what time is it?"` |
| **speak** | Text-to-speech (multiple engines) | `convert text to speech` |
| **realistic_speak** | Natural speech with emotions | `"[S1] hello! (laughs)"` |
</details>
<details>
<summary><strong>🧠 Memory & Data</strong> - Information systems</summary>
| Tool | Purpose | Example |
|------|---------|---------|
| **sqlite_memory** | Local memory with SQL queries | `search conversation history` |
| **memory** | Cloud knowledge base (Bedrock) | `semantic search across docs` |
| **sql_tool** | Universal database client | `connect to PostgreSQL/MySQL` |
| **data_viz_tool** | Create charts and visualizations | `generate sales reports` |
</details>
<details>
<summary><strong>🌐 Integrations</strong> - External services</summary>
| Tool | Purpose | Example |
|------|---------|---------|
| **use_github** | GitHub GraphQL API | `create issues and PRs` |
| **slack** | Team communication | `send messages and alerts` |
| **use_aws** | AWS service integration | `manage EC2, S3, Lambda` |
| **scraper** | Web scraping | `extract data from websites` |
</details>
<details>
<summary><strong>🚀 Advanced</strong> - Power user features</summary>
| Tool | Purpose | Example |
|------|---------|---------|
| **create_subagent** | Distributed AI via GitHub Actions | `delegate complex tasks` |
| **load_tool** | Dynamic tool loading | `install community tools` |
| **tasks** | Background processes | `run monitoring scripts` |
| **workflow** | Complex automation | `orchestrate deployments` |
</details>
## ⚙️ Configuration
### Quick Settings
```bash
# Use different AI providers
MODEL_PROVIDER=anthropic maxs
MODEL_PROVIDER=openai maxs
MODEL_PROVIDER=ollama maxs
# Enable specific tools only
STRANDS_TOOLS="listen,speak,sql_tool,github" maxs
# Enable all tools
STRANDS_TOOLS="ALL" maxs
```
### Team Collaboration (Advanced)
```bash
# Enable team features
export STRANDS_TOOLS="event_bridge,sql_tool,memory"
export AWS_REGION=us-west-2
export MAXS_EVENT_TOPIC=my-team
# Shared knowledge base
export STRANDS_KNOWLEDGE_BASE_ID=team-kb-id
```
### External Services
```bash
# GitHub integration
export GITHUB_TOKEN=your-token
# Slack integration
export SLACK_BOT_TOKEN=xoxb-your-token
export SLACK_APP_TOKEN=xapp-your-token
# AWS services
export AWS_REGION=us-west-2
```
## 💡 Advanced Examples
<details>
<summary><strong>🔥 Hot Reload Tool Creation</strong></summary>
Create and use tools instantly:
```python
# Save to ./tools/crypto.py
from strands import tool
import requests
@tool
def crypto(coin: str) -> str:
"""Get cryptocurrency price."""
response = requests.get(f"https://api.coinbase.com/v2/exchange-rates?currency={coin}")
price = response.json()["data"]["rates"]["USD"]
return f"{coin}: ${price}"
```
Then immediately:
```bash
maxs "get crypto price for bitcoin" # Tool works instantly!
```
</details>
<details>
<summary><strong>📊 Data Analysis Pipeline</strong></summary>
```bash
# Complete workflow in one command
maxs "connect to PostgreSQL, analyze user growth trends, create visualization, and save report to S3"
# Or step by step
maxs "connect to database 'users' on localhost"
maxs "create monthly signup chart for last 6 months"
maxs "export chart as PNG and upload to S3 bucket"
```
</details>
<details>
<summary><strong>🤖 Multi-Agent Workflows</strong></summary>
```bash
# Deploy specialized agents
maxs "create subagent for security audit with GitHub Actions"
maxs "create subagent for performance testing with detailed metrics"
# P2P agent communication (no internet needed)
maxs "start bitchat and enable agent triggers"
# Agents automatically coordinate and share results
```
</details>
## 🛡️ Privacy & Security
**Local-first by design:**
- Core functionality works completely offline
- Conversation history stored locally in `/tmp/.maxs/`
- Custom tools saved in `./tools/` directory
- No external data transmission except to chosen AI provider
**Optional cloud features** (when enabled):
- AWS Bedrock for knowledge base (requires AWS credentials)
- Team collaboration via EventBridge (optional)
- External APIs only when explicitly used (GitHub, Slack, etc.)
## 🔧 Troubleshooting
<details>
<summary><strong>Common Issues</strong></summary>
**AI Provider Problems:**
```bash
# Try local model as fallback
ollama serve && ollama pull qwen3:4b
MODEL_PROVIDER=ollama maxs
```
**Voice Recognition Issues:**
```bash
maxs
> listen(action="list_devices") # Check available microphones
```
**Tool Loading Problems:**
```bash
# Reset and enable all tools
STRANDS_TOOLS="ALL" maxs
```
**Database Connection Issues:**
```bash
maxs
> sql_tool(action="connect", database_type="postgresql", host="localhost")
```
</details>
## 🚀 Why Developers Choose maxs
> *"Started using maxs for quick scripts. Now our entire team builds tools by talking to them. Saved 20 hours last week alone."*
> — DevOps Engineer
**Key advantages:**
- ⚡ **Instant gratification** - Working tools in 30 seconds
- 🎙️ **Voice-first** - Build while you think out loud
- 🔄 **Hot reload** - Iterate without interruption
- 📡 **Distributed** - Team coordination without servers
- 🧠 **Intelligent** - Remembers your context and decisions
---
## 📦 Installation
```bash
pipx install maxs && maxs
```
**Alternative setups:**
- **Development:** `git clone https://github.com/cagataycali/maxs && pip install -e .`
- **Binary:** `pip install maxs[binary]` then `pyinstaller --onefile -m maxs.main`
## 📄 License
MIT - Use it however you want!
Raw data
{
"_id": null,
"home_page": null,
"name": "maxs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, agent, ollama, strands, local, minimalist",
"author": null,
"author_email": "Cagatay Cali <cagataycali@icloud.com>",
"download_url": "https://files.pythonhosted.org/packages/7b/ad/e39803390ae983f65bbab7082434dd55680d113e3de96272f33a02a4434f/maxs-0.29.0.tar.gz",
"platform": null,
"description": "# maxs\n\n**Build AI tools while talking to them**\n\nStop writing configs. Stop restarting servers. Just speak:\n\n*\"max, create a tool that monitors our Kubernetes cluster\"* \n\u2192 Tool created, tested, and running in 30 seconds\n\n## \ud83d\ude80 Try it now (2 minutes)\n\n```bash\npipx install maxs && maxs\n```\n\nThen just speak:\n- *\"max, what time is it?\"* \u2192 Instant response \n- *\"max, create a weather tool\"* \u2192 Tool appears in ./tools/\n- *\"max, use the weather tool for Tokyo\"* \u2192 Working immediately\n\n**No configuration. No API keys. No YAML files.**\n\n## \ud83d\udca1 How it works\n\n```\nVoice Command \u2192 Hot Reload Tool Creation \u2192 Instant Usage\n \u2193 \u2193 \u2193\n\"max, create X\" ./tools/X.py saved Tool ready to use\n```\n\n**Three revolutionary features:**\n\n\ud83c\udf99\ufe0f **Voice-First Development** - Build tools by talking \n\ud83d\udd25 **Instant Hot Reload** - Tools work immediately, no restart \n\ud83d\udce1 **P2P Agent Network** - Agents communicate over encrypted mesh\n\n## \u26a1 Setup (choose one)\n\n**Option 1: Local AI (recommended for privacy)**\n```bash\ncurl -fsSL https://ollama.ai/install.sh | sh\nollama pull qwen3:4b\nmaxs\n```\n\n**Option 2: Cloud AI (recommended for power)**\n```bash\n# Anthropic Claude (best for development)\nexport ANTHROPIC_API_KEY=\"your-key\"\nMODEL_PROVIDER=anthropic maxs\n\n# OpenAI GPT (good for general tasks) \nexport OPENAI_API_KEY=\"your-key\"\nMODEL_PROVIDER=openai maxs\n\n# Other: bedrock, github, litellm, llamaapi, mistral\n```\n\n## \ud83d\udd25 Key Features\n\n### \ud83c\udf99\ufe0f **Voice-Powered Development**\n```bash\nmaxs\n> listen(action=\"start\", trigger_keyword=\"max\")\n\n# Then just speak naturally:\n\"max, analyze the server logs\" \u2192 Creates monitoring tools\n\"max, deploy to staging\" \u2192 Runs deployment scripts \n\"max, create a backup system\" \u2192 Builds automation instantly\n```\n\n### \ud83d\udd04 **Instant Hot Reload**\nCreate tools while maxs is running:\n```python\n# Save this to ./tools/weather.py\nfrom strands import tool\n\n@tool\ndef weather(city: str) -> str:\n return f\"Weather for {city}: 72\u00b0F, sunny\"\n```\n\nThen immediately use it:\n```bash\nmaxs \"get weather for Tokyo\" # Tool works instantly!\n```\n\n### \ud83d\udce1 **P2P Agent Network**\nAgents communicate over encrypted Bluetooth mesh:\n```bash\n# Agent Alice says:\n\"max, analyze the server performance\"\n\n# Agent Bob automatically responds:\n\"Performance analysis complete. CPU at 85%, recommend scaling.\"\n\n# No internet required - direct agent-to-agent communication\n```\n\n### \ud83e\udde0 **Intelligent Memory**\nRemembers everything across sessions:\n```bash\nmaxs \"remember: we're using PostgreSQL for user data\"\n# Later...\nmaxs \"create a user analytics tool\" # Uses PostgreSQL context\n```\n\n## \ud83d\udee0\ufe0f Common Workflows\n\n### Development & Automation\n```bash\nmaxs \"analyze this codebase and suggest improvements\"\nmaxs \"create deployment script for our Docker app\" \nmaxs \"monitor system logs in the background\"\nmaxs \"format all Python files in this project\"\n```\n\n### Data Analysis\n```bash\nmaxs \"connect to PostgreSQL and analyze user growth\"\nmaxs \"create charts from the sales CSV file\"\nmaxs \"query the API and generate a report\"\n```\n\n### Voice Control (Hands-Free)\n```bash\n# Start voice mode first\nmaxs\n> listen(action=\"start\", trigger_keyword=\"max\")\n\n# Then just speak:\n\"max, what's the system status?\"\n\"max, backup the database\" \n\"max, check for security updates\"\n```\n\n## \ud83e\uddf0 Built-in Tools (50+)\n\n<details>\n<summary><strong>\ud83c\udfaf Essential Tools</strong> - Core functionality</summary>\n\n| Tool | Purpose | Example |\n|------|---------|---------|\n| **shell** | Execute commands with real-time output | `check disk usage` |\n| **editor** | File editing with syntax highlighting | `modify config files` |\n| **python_repl** | Interactive Python execution | `run data analysis scripts` |\n| **http_request** | Universal HTTP client | `call any REST API` |\n\n</details>\n\n<details>\n<summary><strong>\ud83c\udf99\ufe0f Voice & Audio</strong> - Speech interaction</summary>\n\n| Tool | Purpose | Example |\n|------|---------|---------|\n| **listen** | Speech-to-text with trigger keywords | `\"max, what time is it?\"` |\n| **speak** | Text-to-speech (multiple engines) | `convert text to speech` |\n| **realistic_speak** | Natural speech with emotions | `\"[S1] hello! (laughs)\"` |\n\n</details>\n\n<details>\n<summary><strong>\ud83e\udde0 Memory & Data</strong> - Information systems</summary>\n\n| Tool | Purpose | Example |\n|------|---------|---------|\n| **sqlite_memory** | Local memory with SQL queries | `search conversation history` |\n| **memory** | Cloud knowledge base (Bedrock) | `semantic search across docs` |\n| **sql_tool** | Universal database client | `connect to PostgreSQL/MySQL` |\n| **data_viz_tool** | Create charts and visualizations | `generate sales reports` |\n\n</details>\n\n<details>\n<summary><strong>\ud83c\udf10 Integrations</strong> - External services</summary>\n\n| Tool | Purpose | Example |\n|------|---------|---------|\n| **use_github** | GitHub GraphQL API | `create issues and PRs` |\n| **slack** | Team communication | `send messages and alerts` |\n| **use_aws** | AWS service integration | `manage EC2, S3, Lambda` |\n| **scraper** | Web scraping | `extract data from websites` |\n\n</details>\n\n<details>\n<summary><strong>\ud83d\ude80 Advanced</strong> - Power user features</summary>\n\n| Tool | Purpose | Example |\n|------|---------|---------|\n| **create_subagent** | Distributed AI via GitHub Actions | `delegate complex tasks` |\n| **load_tool** | Dynamic tool loading | `install community tools` |\n| **tasks** | Background processes | `run monitoring scripts` |\n| **workflow** | Complex automation | `orchestrate deployments` |\n\n</details>\n\n## \u2699\ufe0f Configuration\n\n### Quick Settings\n```bash\n# Use different AI providers\nMODEL_PROVIDER=anthropic maxs\nMODEL_PROVIDER=openai maxs\nMODEL_PROVIDER=ollama maxs\n\n# Enable specific tools only \nSTRANDS_TOOLS=\"listen,speak,sql_tool,github\" maxs\n\n# Enable all tools\nSTRANDS_TOOLS=\"ALL\" maxs\n```\n\n### Team Collaboration (Advanced)\n```bash\n# Enable team features\nexport STRANDS_TOOLS=\"event_bridge,sql_tool,memory\"\nexport AWS_REGION=us-west-2\nexport MAXS_EVENT_TOPIC=my-team\n\n# Shared knowledge base\nexport STRANDS_KNOWLEDGE_BASE_ID=team-kb-id\n```\n\n### External Services\n```bash\n# GitHub integration\nexport GITHUB_TOKEN=your-token\n\n# Slack integration \nexport SLACK_BOT_TOKEN=xoxb-your-token\nexport SLACK_APP_TOKEN=xapp-your-token\n\n# AWS services\nexport AWS_REGION=us-west-2\n```\n\n## \ud83d\udca1 Advanced Examples\n\n<details>\n<summary><strong>\ud83d\udd25 Hot Reload Tool Creation</strong></summary>\n\nCreate and use tools instantly:\n\n```python\n# Save to ./tools/crypto.py\nfrom strands import tool\nimport requests\n\n@tool\ndef crypto(coin: str) -> str:\n \"\"\"Get cryptocurrency price.\"\"\"\n response = requests.get(f\"https://api.coinbase.com/v2/exchange-rates?currency={coin}\")\n price = response.json()[\"data\"][\"rates\"][\"USD\"]\n return f\"{coin}: ${price}\"\n```\n\nThen immediately:\n```bash\nmaxs \"get crypto price for bitcoin\" # Tool works instantly!\n```\n\n</details>\n\n<details>\n<summary><strong>\ud83d\udcca Data Analysis Pipeline</strong></summary>\n\n```bash\n# Complete workflow in one command\nmaxs \"connect to PostgreSQL, analyze user growth trends, create visualization, and save report to S3\"\n\n# Or step by step\nmaxs \"connect to database 'users' on localhost\"\nmaxs \"create monthly signup chart for last 6 months\" \nmaxs \"export chart as PNG and upload to S3 bucket\"\n```\n\n</details>\n\n<details>\n<summary><strong>\ud83e\udd16 Multi-Agent Workflows</strong></summary>\n\n```bash\n# Deploy specialized agents\nmaxs \"create subagent for security audit with GitHub Actions\"\nmaxs \"create subagent for performance testing with detailed metrics\"\n\n# P2P agent communication (no internet needed)\nmaxs \"start bitchat and enable agent triggers\"\n# Agents automatically coordinate and share results\n```\n\n</details>\n\n## \ud83d\udee1\ufe0f Privacy & Security\n\n**Local-first by design:**\n- Core functionality works completely offline\n- Conversation history stored locally in `/tmp/.maxs/`\n- Custom tools saved in `./tools/` directory\n- No external data transmission except to chosen AI provider\n\n**Optional cloud features** (when enabled):\n- AWS Bedrock for knowledge base (requires AWS credentials)\n- Team collaboration via EventBridge (optional)\n- External APIs only when explicitly used (GitHub, Slack, etc.)\n\n## \ud83d\udd27 Troubleshooting\n\n<details>\n<summary><strong>Common Issues</strong></summary>\n\n**AI Provider Problems:**\n```bash\n# Try local model as fallback\nollama serve && ollama pull qwen3:4b\nMODEL_PROVIDER=ollama maxs\n```\n\n**Voice Recognition Issues:**\n```bash\nmaxs\n> listen(action=\"list_devices\") # Check available microphones\n```\n\n**Tool Loading Problems:**\n```bash\n# Reset and enable all tools\nSTRANDS_TOOLS=\"ALL\" maxs\n```\n\n**Database Connection Issues:**\n```bash\nmaxs\n> sql_tool(action=\"connect\", database_type=\"postgresql\", host=\"localhost\")\n```\n\n</details>\n\n## \ud83d\ude80 Why Developers Choose maxs\n\n> *\"Started using maxs for quick scripts. Now our entire team builds tools by talking to them. Saved 20 hours last week alone.\"* \n> \u2014 DevOps Engineer\n\n**Key advantages:**\n- \u26a1 **Instant gratification** - Working tools in 30 seconds\n- \ud83c\udf99\ufe0f **Voice-first** - Build while you think out loud \n- \ud83d\udd04 **Hot reload** - Iterate without interruption\n- \ud83d\udce1 **Distributed** - Team coordination without servers\n- \ud83e\udde0 **Intelligent** - Remembers your context and decisions\n\n---\n\n## \ud83d\udce6 Installation\n\n```bash\npipx install maxs && maxs\n```\n\n**Alternative setups:**\n- **Development:** `git clone https://github.com/cagataycali/maxs && pip install -e .`\n- **Binary:** `pip install maxs[binary]` then `pyinstaller --onefile -m maxs.main`\n\n## \ud83d\udcc4 License\n\nMIT - Use it however you want!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "minimalist ai agent",
"version": "0.29.0",
"project_urls": {
"Changelog": "https://github.com/cagataycali/maxs/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/cagataycali/maxs",
"Issues": "https://github.com/cagataycali/maxs/issues",
"Repository": "https://github.com/cagataycali/maxs"
},
"split_keywords": [
"ai",
" agent",
" ollama",
" strands",
" local",
" minimalist"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b01526a9c6e1b1c257f372aaf50743e88882f9383f18da2826b4fe1f09913e92",
"md5": "0fb9903f996c4e91c094a26885779a5e",
"sha256": "c8c743f5fe758848336fe997165d6c5def42a4c5b27143483d1fc2fffa91957e"
},
"downloads": -1,
"filename": "maxs-0.29.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0fb9903f996c4e91c094a26885779a5e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 138553,
"upload_time": "2025-09-01T22:59:18",
"upload_time_iso_8601": "2025-09-01T22:59:18.182350Z",
"url": "https://files.pythonhosted.org/packages/b0/15/26a9c6e1b1c257f372aaf50743e88882f9383f18da2826b4fe1f09913e92/maxs-0.29.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7bade39803390ae983f65bbab7082434dd55680d113e3de96272f33a02a4434f",
"md5": "e07f06842f6c0723fe34fde99c6c88c1",
"sha256": "afe8684b62ac4d76699b5a851288e3f9c204a503f2fc7cd19823c2746d6b1f51"
},
"downloads": -1,
"filename": "maxs-0.29.0.tar.gz",
"has_sig": false,
"md5_digest": "e07f06842f6c0723fe34fde99c6c88c1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 131484,
"upload_time": "2025-09-01T22:59:22",
"upload_time_iso_8601": "2025-09-01T22:59:22.598507Z",
"url": "https://files.pythonhosted.org/packages/7b/ad/e39803390ae983f65bbab7082434dd55680d113e3de96272f33a02a4434f/maxs-0.29.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 22:59:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cagataycali",
"github_project": "maxs",
"github_not_found": true,
"lcname": "maxs"
}
JSON
