# maxs
minimalist ai agent that learns from your conversations
## quick start
```bash
pipx install maxs
maxs
```
## setup your ai provider
**option 1: local**
```bash
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull qwen3:4b
maxs
```
**option 2: cloud providers**
```bash
# anthropic
export ANTHROPIC_API_KEY="your-key"
MODEL_PROVIDER=anthropic maxs
# openai
export OPENAI_API_KEY="your-key"
MODEL_PROVIDER=openai maxs
# other providers: bedrock, github, litellm, llamaapi, mistral
```
## what makes maxs special
### 🧠 **remembers everything**
- sees your recent shell commands (bash/zsh history)
- remembers past conversations across sessions
- learns from your conversation patterns
### 🛠️ **powerful built-in tools**
- execute shell commands
- scrape websites and parse html
- run background tasks
- network communication
- nested ai workflows
### 🌐 **team awareness (optional)**
when configured with aws, multiple maxs instances can share context:
- local development + github actions + production servers
- team members see each other's work
- coordinated automation across environments
## basic usage
```bash
# ask questions
maxs "what files are in this directory?"
# execute shell commands
maxs "!ls -la"
maxs "!git status"
# analyze and process
maxs "analyze the log file and find errors"
maxs "format all python files in this project"
# web tasks
maxs "scrape news from hacker news"
# automation
maxs "monitor the system logs in background"
```
## built-in tools
### default tools (always available)
| tool | what it does | example |
|------|-------------|---------|
| **bash** | run shell commands safely | `check disk space` |
| **environment** | manage settings | `show all environment variables` |
| **tcp** | network communication | `start a web server on port 8080` |
| **scraper** | get data from websites | `scrape product prices from amazon` |
| **use_agent** | use different ai models for specific tasks | `use gpt-4 to write documentation` |
| **tasks** | run things in background | `monitor logs continuously` |
### optional tools (enable when needed)
| tool | what it does | how to enable |
|------|-------------|---------------|
| **use_computer** | control mouse/keyboard, take screenshots | `STRANDS_TOOLS="bash,environment,tcp,scraper,use_agent,tasks,use_computer" maxs` |
| **dialog** | create interactive forms | `STRANDS_TOOLS="bash,environment,tcp,scraper,use_agent,tasks,dialog" maxs` |
| **event_bridge** | share context with other maxs instances | `STRANDS_TOOLS="bash,environment,tcp,scraper,use_agent,tasks,event_bridge" maxs` |
## smart features
### conversation memory
maxs automatically remembers:
```bash
# session 1
maxs "i'm working on user authentication"
# session 2 (later)
maxs "how's the auth work going?"
# maxs remembers the previous conversation
```
### shell integration
```bash
# maxs sees your recent commands
$ git clone https://github.com/user/repo
$ cd repo
$ maxs "analyze this codebase"
# maxs knows you just cloned a repo and can analyze it
```
### multi-model workflows
```bash
maxs "use claude for creative writing and gpt-4 for code review"
# automatically switches between models for different tasks
```
## team collaboration (advanced)
**first, enable team features:**
```bash
# enable event_bridge tool
export STRANDS_TOOLS="bash,environment,tcp,scraper,use_agent,tasks,event_bridge"
maxs
```
when multiple people use maxs with shared aws setup:
```bash
# developer 1 (local)
maxs "implementing payment processing"
# developer 2 (sees context from dev 1)
maxs "i see you're working on payments, let me test the api"
# ci/cd pipeline (sees both contexts)
maxs "payment feature tested successfully, deploying to staging"
```
**how to enable team mode:**
1. enable event_bridge tool (see above)
2. set up aws credentials (`aws configure`)
3. one person runs: `maxs "setup event bridge for team collaboration"`
4. team members use same aws account
5. everyone's maxs instances share context automatically
## configuration
### basic settings
```bash
# use different ai provider
MODEL_PROVIDER=anthropic maxs
MODEL_PROVIDER=openai maxs
# use specific model
STRANDS_MODEL_ID=claude-sonnet-4-20250514 maxs
# remember more/less history
MAXS_LAST_MESSAGE_COUNT=50 maxs # default: 100
# enable all tools
STRANDS_TOOLS="ALL" maxs
# enable specific tools only
STRANDS_TOOLS="bash,scraper,use_computer" maxs
```
### team settings (advanced)
```bash
# first enable event_bridge
export STRANDS_TOOLS="bash,environment,tcp,scraper,use_agent,tasks,event_bridge"
# aws region for team features
AWS_REGION=us-west-2
# custom team event bus name
MAXS_EVENT_TOPIC=my-team-maxs
# how many team messages to include
MAXS_DISTRIBUTED_EVENT_COUNT=25
```
## custom tools
drop a python file in `./tools/` directory:
```python
# ./tools/calculator.py
from strands import tool
@tool
def calculate_tip(bill: float, tip_percent: float = 18.0) -> dict:
tip = bill * (tip_percent / 100)
total = bill + tip
return {
"status": "success",
"content": [{"text": f"Bill: ${bill:.2f}\nTip: ${tip:.2f}\nTotal: ${total:.2f}"}]
}
```
then use it:
```bash
maxs "calculate tip for a $50 bill"
```
## examples
### development workflow
```bash
maxs "!git status" # check repo status
maxs "analyze code quality issues" # review code
maxs "!pytest -v" # run tests
maxs "format all python files" # clean up code
maxs "!git add . && git commit -m 'refactor'" # commit changes
```
### system administration
```bash
maxs "check system health" # disk, memory, processes
maxs "monitor nginx logs for errors" # background log monitoring
maxs "!systemctl restart nginx" # restart services
```
### content and research
```bash
maxs "scrape latest tech news" # gather information
maxs "summarize the main trends" # analyze content
```
### automation
```bash
maxs "backup important files to cloud" # file management
maxs "monitor website uptime every 5 minutes" # background monitoring
maxs "send alert if disk usage > 90%" # conditional actions
```
### computer interaction (requires use_computer tool)
```bash
# enable computer control
export STRANDS_TOOLS="bash,environment,tcp,scraper,use_agent,tasks,use_computer"
maxs "take screenshot of monitoring dashboard" # visual check
maxs "click the save button" # mouse control
```
## installation options
### standard installation
```bash
pipx install maxs
```
### development installation
```bash
git clone https://github.com/cagataycali/maxs
cd maxs
pip install -e .
```
### binary distribution
```bash
pip install maxs[binary]
pyinstaller --onefile --name maxs -m maxs.main
# creates standalone ./dist/maxs binary
```
## data and privacy
### local storage
- conversations saved in `/tmp/.maxs/`
- shell history integration (read-only)
- no data sent to external services (except your chosen ai provider)
### team mode (optional)
- uses aws eventbridge for team communication
- only shares conversation summaries, not full messages
- you control the aws account and data
- requires explicit enablement of event_bridge tool
## troubleshooting
### common issues
```bash
# ollama not responding
ollama serve
maxs
# tool permissions
BYPASS_TOOL_CONSENT=true maxs
# reset conversation history
rm -rf /tmp/.maxs/
maxs
# enable all tools if something is missing
STRANDS_TOOLS="ALL" maxs
```
### getting help
```bash
maxs "show available tools"
maxs "help with configuration"
maxs "explain how team mode works"
```
## 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/dd/04/e1a2b5df0788820494815f33a82be1b9f362dd89c74a5ef1e4c60642d3d6/maxs-0.10.0.tar.gz",
"platform": null,
"description": "# maxs\n\nminimalist ai agent that learns from your conversations\n\n## quick start\n\n```bash\npipx install maxs\nmaxs\n```\n\n## setup your ai provider\n\n**option 1: local**\n```bash\ncurl -fsSL https://ollama.ai/install.sh | sh\nollama pull qwen3:4b\nmaxs\n```\n\n**option 2: cloud providers**\n```bash\n# anthropic\nexport ANTHROPIC_API_KEY=\"your-key\"\nMODEL_PROVIDER=anthropic maxs\n\n# openai\nexport OPENAI_API_KEY=\"your-key\" \nMODEL_PROVIDER=openai maxs\n\n# other providers: bedrock, github, litellm, llamaapi, mistral\n```\n\n## what makes maxs special\n\n### \ud83e\udde0 **remembers everything**\n- sees your recent shell commands (bash/zsh history)\n- remembers past conversations across sessions\n- learns from your conversation patterns\n\n### \ud83d\udee0\ufe0f **powerful built-in tools**\n- execute shell commands\n- scrape websites and parse html\n- run background tasks\n- network communication\n- nested ai workflows\n\n### \ud83c\udf10 **team awareness (optional)**\nwhen configured with aws, multiple maxs instances can share context:\n- local development + github actions + production servers\n- team members see each other's work\n- coordinated automation across environments\n\n## basic usage\n\n```bash\n# ask questions\nmaxs \"what files are in this directory?\"\n\n# execute shell commands \nmaxs \"!ls -la\"\nmaxs \"!git status\"\n\n# analyze and process\nmaxs \"analyze the log file and find errors\"\nmaxs \"format all python files in this project\"\n\n# web tasks\nmaxs \"scrape news from hacker news\"\n\n# automation\nmaxs \"monitor the system logs in background\"\n```\n\n## built-in tools\n\n### default tools (always available)\n\n| tool | what it does | example |\n|------|-------------|---------|\n| **bash** | run shell commands safely | `check disk space` |\n| **environment** | manage settings | `show all environment variables` |\n| **tcp** | network communication | `start a web server on port 8080` |\n| **scraper** | get data from websites | `scrape product prices from amazon` |\n| **use_agent** | use different ai models for specific tasks | `use gpt-4 to write documentation` |\n| **tasks** | run things in background | `monitor logs continuously` |\n\n### optional tools (enable when needed)\n\n| tool | what it does | how to enable |\n|------|-------------|---------------|\n| **use_computer** | control mouse/keyboard, take screenshots | `STRANDS_TOOLS=\"bash,environment,tcp,scraper,use_agent,tasks,use_computer\" maxs` |\n| **dialog** | create interactive forms | `STRANDS_TOOLS=\"bash,environment,tcp,scraper,use_agent,tasks,dialog\" maxs` |\n| **event_bridge** | share context with other maxs instances | `STRANDS_TOOLS=\"bash,environment,tcp,scraper,use_agent,tasks,event_bridge\" maxs` |\n\n## smart features\n\n### conversation memory\nmaxs automatically remembers:\n```bash\n# session 1\nmaxs \"i'm working on user authentication\"\n\n# session 2 (later)\nmaxs \"how's the auth work going?\"\n# maxs remembers the previous conversation\n```\n\n### shell integration\n```bash\n# maxs sees your recent commands\n$ git clone https://github.com/user/repo\n$ cd repo\n$ maxs \"analyze this codebase\"\n# maxs knows you just cloned a repo and can analyze it\n```\n\n### multi-model workflows\n```bash\nmaxs \"use claude for creative writing and gpt-4 for code review\"\n# automatically switches between models for different tasks\n```\n\n## team collaboration (advanced)\n\n**first, enable team features:**\n```bash\n# enable event_bridge tool\nexport STRANDS_TOOLS=\"bash,environment,tcp,scraper,use_agent,tasks,event_bridge\"\nmaxs\n```\n\nwhen multiple people use maxs with shared aws setup:\n\n```bash\n# developer 1 (local)\nmaxs \"implementing payment processing\"\n\n# developer 2 (sees context from dev 1) \nmaxs \"i see you're working on payments, let me test the api\"\n\n# ci/cd pipeline (sees both contexts)\nmaxs \"payment feature tested successfully, deploying to staging\"\n```\n\n**how to enable team mode:**\n1. enable event_bridge tool (see above)\n2. set up aws credentials (`aws configure`)\n3. one person runs: `maxs \"setup event bridge for team collaboration\"`\n4. team members use same aws account\n5. everyone's maxs instances share context automatically\n\n## configuration\n\n### basic settings\n```bash\n# use different ai provider\nMODEL_PROVIDER=anthropic maxs\nMODEL_PROVIDER=openai maxs\n\n# use specific model\nSTRANDS_MODEL_ID=claude-sonnet-4-20250514 maxs\n\n# remember more/less history\nMAXS_LAST_MESSAGE_COUNT=50 maxs # default: 100\n\n# enable all tools\nSTRANDS_TOOLS=\"ALL\" maxs\n\n# enable specific tools only\nSTRANDS_TOOLS=\"bash,scraper,use_computer\" maxs\n```\n\n### team settings (advanced)\n```bash\n# first enable event_bridge\nexport STRANDS_TOOLS=\"bash,environment,tcp,scraper,use_agent,tasks,event_bridge\"\n\n# aws region for team features\nAWS_REGION=us-west-2\n\n# custom team event bus name \nMAXS_EVENT_TOPIC=my-team-maxs\n\n# how many team messages to include\nMAXS_DISTRIBUTED_EVENT_COUNT=25\n```\n\n## custom tools\n\ndrop a python file in `./tools/` directory:\n\n```python\n# ./tools/calculator.py\nfrom strands import tool\n\n@tool\ndef calculate_tip(bill: float, tip_percent: float = 18.0) -> dict:\n tip = bill * (tip_percent / 100)\n total = bill + tip\n return {\n \"status\": \"success\", \n \"content\": [{\"text\": f\"Bill: ${bill:.2f}\\nTip: ${tip:.2f}\\nTotal: ${total:.2f}\"}]\n }\n```\n\nthen use it:\n```bash\nmaxs \"calculate tip for a $50 bill\"\n```\n\n## examples\n\n### development workflow\n```bash\nmaxs \"!git status\" # check repo status\nmaxs \"analyze code quality issues\" # review code\nmaxs \"!pytest -v\" # run tests \nmaxs \"format all python files\" # clean up code\nmaxs \"!git add . && git commit -m 'refactor'\" # commit changes\n```\n\n### system administration \n```bash\nmaxs \"check system health\" # disk, memory, processes\nmaxs \"monitor nginx logs for errors\" # background log monitoring\nmaxs \"!systemctl restart nginx\" # restart services\n```\n\n### content and research\n```bash\nmaxs \"scrape latest tech news\" # gather information\nmaxs \"summarize the main trends\" # analyze content\n```\n\n### automation\n```bash\nmaxs \"backup important files to cloud\" # file management\nmaxs \"monitor website uptime every 5 minutes\" # background monitoring\nmaxs \"send alert if disk usage > 90%\" # conditional actions\n```\n\n### computer interaction (requires use_computer tool)\n```bash\n# enable computer control\nexport STRANDS_TOOLS=\"bash,environment,tcp,scraper,use_agent,tasks,use_computer\"\nmaxs \"take screenshot of monitoring dashboard\" # visual check\nmaxs \"click the save button\" # mouse control\n```\n\n## installation options\n\n### standard installation\n```bash\npipx install maxs\n```\n\n### development installation\n```bash\ngit clone https://github.com/cagataycali/maxs\ncd maxs\npip install -e .\n```\n\n### binary distribution\n```bash\npip install maxs[binary]\npyinstaller --onefile --name maxs -m maxs.main\n# creates standalone ./dist/maxs binary\n```\n\n## data and privacy\n\n### local storage\n- conversations saved in `/tmp/.maxs/` \n- shell history integration (read-only)\n- no data sent to external services (except your chosen ai provider)\n\n### team mode (optional)\n- uses aws eventbridge for team communication\n- only shares conversation summaries, not full messages\n- you control the aws account and data\n- requires explicit enablement of event_bridge tool\n\n## troubleshooting\n\n### common issues\n```bash\n# ollama not responding\nollama serve\nmaxs\n\n# tool permissions\nBYPASS_TOOL_CONSENT=true maxs\n\n# reset conversation history\nrm -rf /tmp/.maxs/\nmaxs\n\n# enable all tools if something is missing\nSTRANDS_TOOLS=\"ALL\" maxs\n```\n\n### getting help\n```bash\nmaxs \"show available tools\"\nmaxs \"help with configuration\" \nmaxs \"explain how team mode works\"\n```\n\n## license\n\nmit - use it however you want\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "minimalist ai agent",
"version": "0.10.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": "2a080a34f479cc25b62ae00012b76ed0f12bb6d1b0383db1b2f8628d87bcb8a6",
"md5": "9bca4b3b2e8749fdc963d25d58d602b6",
"sha256": "2ff6f0d1cd4939b69dc13f7b789c32a1cf0a97557c763b90fe5f4f074ad038fc"
},
"downloads": -1,
"filename": "maxs-0.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9bca4b3b2e8749fdc963d25d58d602b6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 85370,
"upload_time": "2025-07-15T17:32:24",
"upload_time_iso_8601": "2025-07-15T17:32:24.547451Z",
"url": "https://files.pythonhosted.org/packages/2a/08/0a34f479cc25b62ae00012b76ed0f12bb6d1b0383db1b2f8628d87bcb8a6/maxs-0.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dd04e1a2b5df0788820494815f33a82be1b9f362dd89c74a5ef1e4c60642d3d6",
"md5": "7daf3f2c7e5266d39c48d2cc545e72e3",
"sha256": "8f77212be7c65a2c2e91d577bf82974d75202e331464d96c06465574df0798c1"
},
"downloads": -1,
"filename": "maxs-0.10.0.tar.gz",
"has_sig": false,
"md5_digest": "7daf3f2c7e5266d39c48d2cc545e72e3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 78763,
"upload_time": "2025-07-15T17:32:25",
"upload_time_iso_8601": "2025-07-15T17:32:25.438834Z",
"url": "https://files.pythonhosted.org/packages/dd/04/e1a2b5df0788820494815f33a82be1b9f362dd89c74a5ef1e4c60642d3d6/maxs-0.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 17:32:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cagataycali",
"github_project": "maxs",
"github_not_found": true,
"lcname": "maxs"
}
JSON
