# 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 |
|------|-------------|---------------|
| **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" 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
```
## 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/b9/87/32117d919d75caaf469b4c9495ee8fae8efba21a3abde7575b693c1969b4/maxs-0.14.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| **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\" 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## 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.14.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": "4f86dc1bf82f0fe5afab519e7365b891f4d416b95029e187f48e1cd4c46651bd",
"md5": "7337b45a0b1680c0e92711dd4ce85702",
"sha256": "c90fbba79c1b5b067f635c2d16e667bc19e159b17467443d3d727a6d98764721"
},
"downloads": -1,
"filename": "maxs-0.14.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7337b45a0b1680c0e92711dd4ce85702",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 83688,
"upload_time": "2025-07-29T01:39:38",
"upload_time_iso_8601": "2025-07-29T01:39:38.591762Z",
"url": "https://files.pythonhosted.org/packages/4f/86/dc1bf82f0fe5afab519e7365b891f4d416b95029e187f48e1cd4c46651bd/maxs-0.14.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b98732117d919d75caaf469b4c9495ee8fae8efba21a3abde7575b693c1969b4",
"md5": "56be9b25a358004fb8048d51c55bd713",
"sha256": "3b6ecf29760d4cccc6ec56c9705b133c2de3b2f21cb0f43719ad0b777eadd490"
},
"downloads": -1,
"filename": "maxs-0.14.0.tar.gz",
"has_sig": false,
"md5_digest": "56be9b25a358004fb8048d51c55bd713",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 79506,
"upload_time": "2025-07-29T01:39:39",
"upload_time_iso_8601": "2025-07-29T01:39:39.564865Z",
"url": "https://files.pythonhosted.org/packages/b9/87/32117d919d75caaf469b4c9495ee8fae8efba21a3abde7575b693c1969b4/maxs-0.14.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 01:39:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cagataycali",
"github_project": "maxs",
"github_not_found": true,
"lcname": "maxs"
}
JSON
