patchpal 0.1.7__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. {patchpal-0.1.7/patchpal.egg-info → patchpal-0.3.0}/PKG-INFO +153 -59
  2. {patchpal-0.1.7 → patchpal-0.3.0}/README.md +152 -58
  3. {patchpal-0.1.7 → patchpal-0.3.0}/patchpal/__init__.py +1 -1
  4. {patchpal-0.1.7 → patchpal-0.3.0}/patchpal/agent.py +94 -9
  5. {patchpal-0.1.7 → patchpal-0.3.0}/patchpal/cli.py +5 -2
  6. {patchpal-0.1.7 → patchpal-0.3.0}/patchpal/context.py +5 -4
  7. {patchpal-0.1.7 → patchpal-0.3.0}/patchpal/system_prompt.md +2 -1
  8. {patchpal-0.1.7 → patchpal-0.3.0}/patchpal/tools.py +181 -54
  9. {patchpal-0.1.7 → patchpal-0.3.0/patchpal.egg-info}/PKG-INFO +153 -59
  10. {patchpal-0.1.7 → patchpal-0.3.0}/tests/test_agent.py +100 -0
  11. {patchpal-0.1.7 → patchpal-0.3.0}/tests/test_tools.py +261 -11
  12. {patchpal-0.1.7 → patchpal-0.3.0}/LICENSE +0 -0
  13. {patchpal-0.1.7 → patchpal-0.3.0}/MANIFEST.in +0 -0
  14. {patchpal-0.1.7 → patchpal-0.3.0}/patchpal/permissions.py +0 -0
  15. {patchpal-0.1.7 → patchpal-0.3.0}/patchpal/skills.py +0 -0
  16. {patchpal-0.1.7 → patchpal-0.3.0}/patchpal.egg-info/SOURCES.txt +0 -0
  17. {patchpal-0.1.7 → patchpal-0.3.0}/patchpal.egg-info/dependency_links.txt +0 -0
  18. {patchpal-0.1.7 → patchpal-0.3.0}/patchpal.egg-info/entry_points.txt +0 -0
  19. {patchpal-0.1.7 → patchpal-0.3.0}/patchpal.egg-info/requires.txt +0 -0
  20. {patchpal-0.1.7 → patchpal-0.3.0}/patchpal.egg-info/top_level.txt +0 -0
  21. {patchpal-0.1.7 → patchpal-0.3.0}/pyproject.toml +0 -0
  22. {patchpal-0.1.7 → patchpal-0.3.0}/setup.cfg +0 -0
  23. {patchpal-0.1.7 → patchpal-0.3.0}/tests/test_cli.py +0 -0
  24. {patchpal-0.1.7 → patchpal-0.3.0}/tests/test_context.py +0 -0
  25. {patchpal-0.1.7 → patchpal-0.3.0}/tests/test_guardrails.py +0 -0
  26. {patchpal-0.1.7 → patchpal-0.3.0}/tests/test_operational_safety.py +0 -0
  27. {patchpal-0.1.7 → patchpal-0.3.0}/tests/test_skills.py +0 -0
{patchpal-0.1.7/patchpal.egg-info → patchpal-0.3.0}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: patchpal
3
- Version: 0.1.7
3
+ Version: 0.3.0
4
4
  Summary: A lean Claude Code clone in pure Python
5
5
  Author: PatchPal Contributors
6
6
  License-Expression: Apache-2.0
@@ -46,6 +46,30 @@ Dynamic: license-file
46
46
 
47
47
  A key goal of this project is to approximate Claude Code's core functionality while remaining lean, accessible, and configurable, enabling learning, experimentation, and broad applicability across use cases.
48
48
 
49
+ ## Table of Contents
50
+
51
+ - [Installation](https://github.com/amaiya/patchpal?tab=readme-ov-file#installation)
52
+ - [Setup](https://github.com/amaiya/patchpal?tab=readme-ov-file#setup)
53
+ - [Features](https://github.com/amaiya/patchpal?tab=readme-ov-file#features)
54
+ - [Tools](https://github.com/amaiya/patchpal?tab=readme-ov-file#tools)
55
+ - [File Operations](https://github.com/amaiya/patchpal?tab=readme-ov-file#file-operations)
56
+ - [Task Planning (TODO System)](https://github.com/amaiya/patchpal?tab=readme-ov-file#task-planning-todo-system)
57
+ - [User Interaction](https://github.com/amaiya/patchpal?tab=readme-ov-file#user-interaction)
58
+ - [Git Operations](https://github.com/amaiya/patchpal?tab=readme-ov-file#git-operations-no-permission-required)
59
+ - [Web Capabilities](https://github.com/amaiya/patchpal?tab=readme-ov-file#web-capabilities-requires-permission)
60
+ - [Skills System](https://github.com/amaiya/patchpal?tab=readme-ov-file#skills-system)
61
+ - [Model Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#model-configuration)
62
+ - [Supported Models](https://github.com/amaiya/patchpal?tab=readme-ov-file#supported-models)
63
+ - [Using Local Models (vLLM & Ollama)](https://github.com/amaiya/patchpal?tab=readme-ov-file#using-local-models-vllm--ollama)
64
+ - [Air-Gapped and Offline Environments](https://github.com/amaiya/patchpal?tab=readme-ov-file#air-gapped-and-offline-environments)
65
+ - [Maximum Security Mode](https://github.com/amaiya/patchpal?tab=readme-ov-file#maximum-security-mode)
66
+ - [Usage](https://github.com/amaiya/patchpal?tab=readme-ov-file#usage)
67
+ - [Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#configuration)
68
+ - [Example Tasks](https://github.com/amaiya/patchpal?tab=readme-ov-file#example-tasks)
69
+ - [Safety](https://github.com/amaiya/patchpal?tab=readme-ov-file#safety)
70
+ - [Context Management](https://github.com/amaiya/patchpal?tab=readme-ov-file#context-management)
71
+ - [Troubleshooting](https://github.com/amaiya/patchpal?tab=readme-ov-file#troubleshooting)
72
+
49
73
 
50
74
  ```bash
51
75
  $ls ./patchpal
@@ -463,6 +487,7 @@ docker rm ollama
463
487
 
464
488
  # Start with proper configuration
465
489
  docker run -d \
490
+ --gpus all \
466
491
  -e OLLAMA_CONTEXT_LENGTH=32768 \
467
492
  -v ollama:/root/.ollama \
468
493
  -p 11434:11434 \
@@ -643,6 +668,116 @@ The agent will process your request and show you the results. You can continue w
643
668
  - **Interrupt Agent**: Press `Ctrl-C` during agent execution to stop the current task without exiting PatchPal
644
669
  - **Exit**: Type `exit`, `quit`, or press `Ctrl-C` at the prompt to exit PatchPal
645
670
 
671
+ ## Configuration
672
+
673
+ PatchPal can be configured through `PATCHPAL_*` environment variables to customize behavior, security, and performance.
674
+
675
+ ### Model Selection
676
+
677
+ ```bash
678
+ export PATCHPAL_MODEL=openai/gpt-4o # Override default model
679
+ # Priority: CLI arg > PATCHPAL_MODEL env var > default (anthropic/claude-sonnet-4-5)
680
+ ```
681
+
682
+ ### Security & Permissions
683
+
684
+ ```bash
685
+ # Permission System
686
+ export PATCHPAL_REQUIRE_PERMISSION=true # Prompt before executing commands/modifying files (default: true)
687
+ # ⚠️ WARNING: Setting to false disables prompts - only use in trusted environments
688
+
689
+ # File Safety
690
+ export PATCHPAL_MAX_FILE_SIZE=10485760 # Maximum file size in bytes for read/write (default: 10MB)
691
+ export PATCHPAL_READ_ONLY=true # Prevent ALL file modifications (default: false)
692
+ # Useful for: code review, exploration, security audits
693
+ export PATCHPAL_ALLOW_SENSITIVE=true # Allow access to .env, credentials (default: false - blocked)
694
+ # Only enable with test/dummy credentials
695
+
696
+ # Command Safety
697
+ export PATCHPAL_ALLOW_SUDO=true # Allow sudo/privilege escalation (default: false - blocked)
698
+ # ⚠️ WARNING: Only enable in trusted, controlled environments
699
+ export PATCHPAL_SHELL_TIMEOUT=60 # Shell command timeout in seconds (default: 30)
700
+ ```
701
+
702
+ ### Operational Controls
703
+
704
+ ```bash
705
+ # Logging & Auditing
706
+ export PATCHPAL_AUDIT_LOG=false # Log operations to ~/.patchpal/<repo-name>/audit.log (default: true)
707
+ export PATCHPAL_ENABLE_BACKUPS=true # Auto-backup files before modification (default: false)
708
+
709
+ # Resource Limits
710
+ export PATCHPAL_MAX_OPERATIONS=10000 # Max operations per session (default: 10000)
711
+ export PATCHPAL_MAX_ITERATIONS=150 # Max agent iterations per task (default: 100)
712
+ # Increase for complex multi-file tasks
713
+ ```
714
+
715
+ ### Context Window Management
716
+
717
+ ```bash
718
+ # Auto-Compaction
719
+ export PATCHPAL_DISABLE_AUTOCOMPACT=true # Disable auto-compaction (default: false - enabled)
720
+ export PATCHPAL_COMPACT_THRESHOLD=0.75 # Trigger compaction at % full (default: 0.75 = 75%)
721
+
722
+ # Context Limits
723
+ export PATCHPAL_CONTEXT_LIMIT=100000 # Override model's context limit (for testing)
724
+ # Leave unset to use model's actual capacity
725
+
726
+ # Pruning Controls
727
+ export PATCHPAL_PRUNE_PROTECT=40000 # Keep last N tokens of tool outputs (default: 40000)
728
+ export PATCHPAL_PRUNE_MINIMUM=20000 # Minimum tokens to prune (default: 20000)
729
+ ```
730
+
731
+ ### Web Tools
732
+
733
+ ```bash
734
+ # Enable/Disable Web Access
735
+ export PATCHPAL_ENABLE_WEB=false # Disable web search/fetch for air-gapped environments (default: true)
736
+
737
+ # Web Request Limits
738
+ export PATCHPAL_WEB_TIMEOUT=60 # Web request timeout in seconds (default: 30)
739
+ export PATCHPAL_MAX_WEB_SIZE=10485760 # Max web content size in bytes (default: 5MB)
740
+ export PATCHPAL_MAX_WEB_CHARS=500000 # Max characters from web content (default: 500k ≈ 125k tokens)
741
+ ```
742
+
743
+ ### Custom System Prompt
744
+
745
+ ```bash
746
+ export PATCHPAL_SYSTEM_PROMPT=~/.patchpal/my_prompt.md # Use custom system prompt
747
+ # File can use template variables: {current_date}, {platform_info}
748
+ # Useful for: custom behavior, team standards, domain-specific instructions
749
+ ```
750
+
751
+ ### Configuration Examples
752
+
753
+ **Air-Gapped Environment (Offline, No Web Access):**
754
+ ```bash
755
+ export PATCHPAL_ENABLE_WEB=false
756
+ patchpal --model hosted_vllm/openai/gpt-oss-20b
757
+ ```
758
+
759
+ **Maximum Security (Read-Only Analysis):**
760
+ ```bash
761
+ export PATCHPAL_READ_ONLY=true
762
+ export PATCHPAL_REQUIRE_PERMISSION=true
763
+ patchpal --require-permission-for-all
764
+ ```
765
+
766
+ **Testing Context Management:**
767
+ ```bash
768
+ export PATCHPAL_CONTEXT_LIMIT=10000 # Small limit to trigger compaction quickly
769
+ export PATCHPAL_COMPACT_THRESHOLD=0.75 # Trigger at 75% instead of 85%
770
+ export PATCHPAL_PRUNE_PROTECT=500 # Keep only last 500 tokens
771
+ patchpal
772
+ ```
773
+
774
+ **Autonomous Mode (Trusted Environment Only):**
775
+ ```bash
776
+ export PATCHPAL_REQUIRE_PERMISSION=false # ⚠️ Disables all permission prompts
777
+ export PATCHPAL_MAX_ITERATIONS=200 # Allow longer runs
778
+ patchpal
779
+ ```
780
+
646
781
  ## Example Tasks
647
782
 
648
783
  ```
@@ -706,43 +841,7 @@ PatchPal includes comprehensive security protections enabled by default:
706
841
  - **Resource limits**: Configurable operation counter prevents infinite loops (10000 operations default)
707
842
  - **Git state awareness**: Warns when modifying files with uncommitted changes
708
843
 
709
- **Configuration via environment variables:**
710
- ```bash
711
- # Critical Security Controls
712
- export PATCHPAL_REQUIRE_PERMISSION=true # Prompt for permission before executing commands/modifying files (default: true)
713
- # ⚠️ WARNING: Setting to false disables prompts - only use in trusted, controlled environments
714
- # When disabled, the agent can modify files and run commands without asking
715
- export PATCHPAL_MAX_FILE_SIZE=5242880 # Maximum file size in bytes for read/write operations (default: 10485760 = 10MB)
716
- export PATCHPAL_READ_ONLY=true # Prevent all file modifications, analysis-only mode (default: false)
717
- # Useful for: code review, exploration, security audits, CI/CD analysis, or trying PatchPal risk-free
718
- export PATCHPAL_ALLOW_SENSITIVE=true # Allow access to .env, credentials, API keys (default: false - blocked for safety)
719
- # Only enable when working with test/dummy credentials or intentionally managing config files
720
- export PATCHPAL_ALLOW_SUDO=true # Allow sudo commands (default: false - blocked for safety)
721
- # ⚠️ WARNING: Only enable in trusted, controlled environments where sudo is necessary
722
- # When enabled, all privilege escalation blocking is disabled
723
-
724
- # Operational Safety Controls
725
- export PATCHPAL_AUDIT_LOG=false # Log all operations to ~/.patchpal/<repo-name>/audit.log (default: true)
726
- export PATCHPAL_ENABLE_BACKUPS=true # Auto-backup files to ~/.patchpal/<repo-name>/backups/ before modification (default: false)
727
- export PATCHPAL_MAX_OPERATIONS=5000 # Maximum operations per session to prevent infinite loops (default: 10000)
728
- export PATCHPAL_MAX_ITERATIONS=150 # Maximum agent iterations per task (default: 100)
729
- # Increase for very complex multi-file tasks, decrease for testing
730
-
731
- # Customization
732
- export PATCHPAL_SYSTEM_PROMPT=~/.patchpal/my_prompt.md # Use custom system prompt file (default: built-in prompt)
733
- # The file can use template variables like {current_date}, {platform_info}, etc.
734
- # Useful for: custom agent behavior, team standards, domain-specific instructions
735
-
736
- # Web Tool Controls
737
- export PATCHPAL_ENABLE_WEB=false # Enable/disable web search and fetch tools (default: true)
738
- # Set to false for air-gapped or offline environments
739
- export PATCHPAL_WEB_TIMEOUT=60 # Timeout for web requests in seconds (default: 30)
740
- export PATCHPAL_MAX_WEB_SIZE=10485760 # Maximum web content size in bytes (default: 5242880 = 5MB)
741
- export PATCHPAL_MAX_WEB_CHARS=500000 # Maximum characters from web content to prevent context overflow (default: 500000 ≈ 125k tokens)
742
-
743
- # Shell Command Controls
744
- export PATCHPAL_SHELL_TIMEOUT=60 # Timeout for shell commands in seconds (default: 30)
745
- ```
844
+ See the [Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#configuration) section for all available `PATCHPAL_*` environment variables to customize security, permissions, logging, and more.
746
845
 
747
846
  **Permission System:**
748
847
 
@@ -793,7 +892,7 @@ PatchPal automatically manages the context window to prevent "input too long" er
793
892
  **Features:**
794
893
  - **Automatic token tracking**: Monitors context usage in real-time
795
894
  - **Smart pruning**: Removes old tool outputs (keeps last 40k tokens) before resorting to full compaction
796
- - **Auto-compaction**: Summarizes conversation history when approaching 85% capacity
895
+ - **Auto-compaction**: Summarizes conversation history when approaching 75% capacity
797
896
  - **Manual control**: Check status with `/status`, disable with environment variable
798
897
 
799
898
  **Commands:**
@@ -818,20 +917,12 @@ You: /compact
818
917
  ```
819
918
 
820
919
  **Configuration:**
821
- ```bash
822
- # Disable auto-compaction (not recommended for long sessions)
823
- export PATCHPAL_DISABLE_AUTOCOMPACT=true
824
920
 
825
- # Adjust compaction threshold (default: 0.85 = 85%)
826
- export PATCHPAL_COMPACT_THRESHOLD=0.90
827
-
828
- # Adjust pruning thresholds
829
- export PATCHPAL_PRUNE_PROTECT=40000 # Keep last 40k tokens (default)
830
- export PATCHPAL_PRUNE_MINIMUM=20000 # Min tokens to prune (default)
831
-
832
- # Override context limit for testing (useful for testing compaction with small values)
833
- export PATCHPAL_CONTEXT_LIMIT=10000 # Force 10k token limit instead of model default
834
- ```
921
+ See the [Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#configuration) section for context management settings including:
922
+ - `PATCHPAL_DISABLE_AUTOCOMPACT` - Disable auto-compaction
923
+ - `PATCHPAL_COMPACT_THRESHOLD` - Adjust compaction threshold
924
+ - `PATCHPAL_CONTEXT_LIMIT` - Override context limit for testing
925
+ - `PATCHPAL_PRUNE_PROTECT` / `PATCHPAL_PRUNE_MINIMUM` - Pruning controls
835
926
 
836
927
  **Testing Context Management:**
837
928
 
@@ -840,7 +931,7 @@ You can test the context management system with small values to trigger compacti
840
931
  ```bash
841
932
  # Set up small context window for testing
842
933
  export PATCHPAL_CONTEXT_LIMIT=10000 # Force 10k token limit (instead of 200k for Claude)
843
- export PATCHPAL_COMPACT_THRESHOLD=0.75 # Trigger at 75% (instead of 85%)
934
+ export PATCHPAL_COMPACT_THRESHOLD=0.75 # Trigger at 75% (default, but shown for clarity)
844
935
  # Note: System prompt + output reserve = ~6.4k tokens baseline
845
936
  # So 75% of 10k = 7.5k, leaving ~1k for conversation
846
937
  export PATCHPAL_PRUNE_PROTECT=500 # Keep only last 500 tokens of tool outputs
@@ -860,9 +951,9 @@ You: /status
860
951
  # Continue - should see pruning messages
861
952
  You: search for "context" in all files
862
953
  # You should see:
863
- # ⚠️ Context window at 85% capacity. Compacting...
954
+ # ⚠️ Context window at 75% capacity. Compacting...
864
955
  # Pruned old tool outputs (saved ~400 tokens)
865
- # ✓ Compaction complete. Saved 850 tokens (85% → 68%)
956
+ # ✓ Compaction complete. Saved 850 tokens (75% → 58%)
866
957
  ```
867
958
 
868
959
  **How It Works:**
@@ -893,7 +984,7 @@ Context Window Status
893
984
  Usage: 80%
894
985
  [████████████████████████████████████████░░░░░░░░░]
895
986
 
896
- Auto-compaction: Enabled (triggers at 85%)
987
+ Auto-compaction: Enabled (triggers at 75%)
897
988
  ======================================================================
898
989
  ```
899
990
 
@@ -903,10 +994,13 @@ The system ensures you can work for extended periods without hitting context lim
903
994
 
904
995
  **Error: "maximum iterations reached"**
905
996
  - The default number of iterations is 100.
906
- - You can increase by setting the environment variable, `export PATCHPAL_MAX_ITERATIONS`
997
+ - Increase with `export PATCHPAL_MAX_ITERATIONS=200` (see [Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#configuration))
907
998
 
908
999
  **Error: "Context Window Error - Input is too long"**
909
1000
  - PatchPal includes automatic context management (compaction) to prevent this error.
910
- - Use `/status` to check your context window usage.
1001
+ - **Quick fix:** Run `/compact` to immediately compact the conversation history and free up space.
1002
+ - Use `/status` to check your context window usage and see how close you are to the limit.
911
1003
  - If auto-compaction is disabled, re-enable it: `unset PATCHPAL_DISABLE_AUTOCOMPACT`
912
- - Context is automatically managed at 85% capacity through pruning and compaction.
1004
+ - Context is automatically managed at 75% capacity through pruning and compaction.
1005
+ - **Note:** Token estimation may be slightly inaccurate compared to the model's actual counting. If you see this error despite auto-compaction being enabled, the 75% threshold may need to be lowered further for your workload. You can adjust it with `export PATCHPAL_COMPACT_THRESHOLD=0.70` (or lower).
1006
+ - See [Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#configuration) for context management settings.
{patchpal-0.1.7 → patchpal-0.3.0}/README.md RENAMED
@@ -9,6 +9,30 @@
9
9
 
10
10
  A key goal of this project is to approximate Claude Code's core functionality while remaining lean, accessible, and configurable, enabling learning, experimentation, and broad applicability across use cases.
11
11
 
12
+ ## Table of Contents
13
+
14
+ - [Installation](https://github.com/amaiya/patchpal?tab=readme-ov-file#installation)
15
+ - [Setup](https://github.com/amaiya/patchpal?tab=readme-ov-file#setup)
16
+ - [Features](https://github.com/amaiya/patchpal?tab=readme-ov-file#features)
17
+ - [Tools](https://github.com/amaiya/patchpal?tab=readme-ov-file#tools)
18
+ - [File Operations](https://github.com/amaiya/patchpal?tab=readme-ov-file#file-operations)
19
+ - [Task Planning (TODO System)](https://github.com/amaiya/patchpal?tab=readme-ov-file#task-planning-todo-system)
20
+ - [User Interaction](https://github.com/amaiya/patchpal?tab=readme-ov-file#user-interaction)
21
+ - [Git Operations](https://github.com/amaiya/patchpal?tab=readme-ov-file#git-operations-no-permission-required)
22
+ - [Web Capabilities](https://github.com/amaiya/patchpal?tab=readme-ov-file#web-capabilities-requires-permission)
23
+ - [Skills System](https://github.com/amaiya/patchpal?tab=readme-ov-file#skills-system)
24
+ - [Model Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#model-configuration)
25
+ - [Supported Models](https://github.com/amaiya/patchpal?tab=readme-ov-file#supported-models)
26
+ - [Using Local Models (vLLM & Ollama)](https://github.com/amaiya/patchpal?tab=readme-ov-file#using-local-models-vllm--ollama)
27
+ - [Air-Gapped and Offline Environments](https://github.com/amaiya/patchpal?tab=readme-ov-file#air-gapped-and-offline-environments)
28
+ - [Maximum Security Mode](https://github.com/amaiya/patchpal?tab=readme-ov-file#maximum-security-mode)
29
+ - [Usage](https://github.com/amaiya/patchpal?tab=readme-ov-file#usage)
30
+ - [Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#configuration)
31
+ - [Example Tasks](https://github.com/amaiya/patchpal?tab=readme-ov-file#example-tasks)
32
+ - [Safety](https://github.com/amaiya/patchpal?tab=readme-ov-file#safety)
33
+ - [Context Management](https://github.com/amaiya/patchpal?tab=readme-ov-file#context-management)
34
+ - [Troubleshooting](https://github.com/amaiya/patchpal?tab=readme-ov-file#troubleshooting)
35
+
12
36
 
13
37
  ```bash
14
38
  $ls ./patchpal
@@ -426,6 +450,7 @@ docker rm ollama
426
450
 
427
451
  # Start with proper configuration
428
452
  docker run -d \
453
+ --gpus all \
429
454
  -e OLLAMA_CONTEXT_LENGTH=32768 \
430
455
  -v ollama:/root/.ollama \
431
456
  -p 11434:11434 \
@@ -606,6 +631,116 @@ The agent will process your request and show you the results. You can continue w
606
631
  - **Interrupt Agent**: Press `Ctrl-C` during agent execution to stop the current task without exiting PatchPal
607
632
  - **Exit**: Type `exit`, `quit`, or press `Ctrl-C` at the prompt to exit PatchPal
608
633
 
634
+ ## Configuration
635
+
636
+ PatchPal can be configured through `PATCHPAL_*` environment variables to customize behavior, security, and performance.
637
+
638
+ ### Model Selection
639
+
640
+ ```bash
641
+ export PATCHPAL_MODEL=openai/gpt-4o # Override default model
642
+ # Priority: CLI arg > PATCHPAL_MODEL env var > default (anthropic/claude-sonnet-4-5)
643
+ ```
644
+
645
+ ### Security & Permissions
646
+
647
+ ```bash
648
+ # Permission System
649
+ export PATCHPAL_REQUIRE_PERMISSION=true # Prompt before executing commands/modifying files (default: true)
650
+ # ⚠️ WARNING: Setting to false disables prompts - only use in trusted environments
651
+
652
+ # File Safety
653
+ export PATCHPAL_MAX_FILE_SIZE=10485760 # Maximum file size in bytes for read/write (default: 10MB)
654
+ export PATCHPAL_READ_ONLY=true # Prevent ALL file modifications (default: false)
655
+ # Useful for: code review, exploration, security audits
656
+ export PATCHPAL_ALLOW_SENSITIVE=true # Allow access to .env, credentials (default: false - blocked)
657
+ # Only enable with test/dummy credentials
658
+
659
+ # Command Safety
660
+ export PATCHPAL_ALLOW_SUDO=true # Allow sudo/privilege escalation (default: false - blocked)
661
+ # ⚠️ WARNING: Only enable in trusted, controlled environments
662
+ export PATCHPAL_SHELL_TIMEOUT=60 # Shell command timeout in seconds (default: 30)
663
+ ```
664
+
665
+ ### Operational Controls
666
+
667
+ ```bash
668
+ # Logging & Auditing
669
+ export PATCHPAL_AUDIT_LOG=false # Log operations to ~/.patchpal/<repo-name>/audit.log (default: true)
670
+ export PATCHPAL_ENABLE_BACKUPS=true # Auto-backup files before modification (default: false)
671
+
672
+ # Resource Limits
673
+ export PATCHPAL_MAX_OPERATIONS=10000 # Max operations per session (default: 10000)
674
+ export PATCHPAL_MAX_ITERATIONS=150 # Max agent iterations per task (default: 100)
675
+ # Increase for complex multi-file tasks
676
+ ```
677
+
678
+ ### Context Window Management
679
+
680
+ ```bash
681
+ # Auto-Compaction
682
+ export PATCHPAL_DISABLE_AUTOCOMPACT=true # Disable auto-compaction (default: false - enabled)
683
+ export PATCHPAL_COMPACT_THRESHOLD=0.75 # Trigger compaction at % full (default: 0.75 = 75%)
684
+
685
+ # Context Limits
686
+ export PATCHPAL_CONTEXT_LIMIT=100000 # Override model's context limit (for testing)
687
+ # Leave unset to use model's actual capacity
688
+
689
+ # Pruning Controls
690
+ export PATCHPAL_PRUNE_PROTECT=40000 # Keep last N tokens of tool outputs (default: 40000)
691
+ export PATCHPAL_PRUNE_MINIMUM=20000 # Minimum tokens to prune (default: 20000)
692
+ ```
693
+
694
+ ### Web Tools
695
+
696
+ ```bash
697
+ # Enable/Disable Web Access
698
+ export PATCHPAL_ENABLE_WEB=false # Disable web search/fetch for air-gapped environments (default: true)
699
+
700
+ # Web Request Limits
701
+ export PATCHPAL_WEB_TIMEOUT=60 # Web request timeout in seconds (default: 30)
702
+ export PATCHPAL_MAX_WEB_SIZE=10485760 # Max web content size in bytes (default: 5MB)
703
+ export PATCHPAL_MAX_WEB_CHARS=500000 # Max characters from web content (default: 500k ≈ 125k tokens)
704
+ ```
705
+
706
+ ### Custom System Prompt
707
+
708
+ ```bash
709
+ export PATCHPAL_SYSTEM_PROMPT=~/.patchpal/my_prompt.md # Use custom system prompt
710
+ # File can use template variables: {current_date}, {platform_info}
711
+ # Useful for: custom behavior, team standards, domain-specific instructions
712
+ ```
713
+
714
+ ### Configuration Examples
715
+
716
+ **Air-Gapped Environment (Offline, No Web Access):**
717
+ ```bash
718
+ export PATCHPAL_ENABLE_WEB=false
719
+ patchpal --model hosted_vllm/openai/gpt-oss-20b
720
+ ```
721
+
722
+ **Maximum Security (Read-Only Analysis):**
723
+ ```bash
724
+ export PATCHPAL_READ_ONLY=true
725
+ export PATCHPAL_REQUIRE_PERMISSION=true
726
+ patchpal --require-permission-for-all
727
+ ```
728
+
729
+ **Testing Context Management:**
730
+ ```bash
731
+ export PATCHPAL_CONTEXT_LIMIT=10000 # Small limit to trigger compaction quickly
732
+ export PATCHPAL_COMPACT_THRESHOLD=0.75 # Trigger at 75% instead of 85%
733
+ export PATCHPAL_PRUNE_PROTECT=500 # Keep only last 500 tokens
734
+ patchpal
735
+ ```
736
+
737
+ **Autonomous Mode (Trusted Environment Only):**
738
+ ```bash
739
+ export PATCHPAL_REQUIRE_PERMISSION=false # ⚠️ Disables all permission prompts
740
+ export PATCHPAL_MAX_ITERATIONS=200 # Allow longer runs
741
+ patchpal
742
+ ```
743
+
609
744
  ## Example Tasks
610
745
 
611
746
  ```
@@ -669,43 +804,7 @@ PatchPal includes comprehensive security protections enabled by default:
669
804
  - **Resource limits**: Configurable operation counter prevents infinite loops (10000 operations default)
670
805
  - **Git state awareness**: Warns when modifying files with uncommitted changes
671
806
 
672
- **Configuration via environment variables:**
673
- ```bash
674
- # Critical Security Controls
675
- export PATCHPAL_REQUIRE_PERMISSION=true # Prompt for permission before executing commands/modifying files (default: true)
676
- # ⚠️ WARNING: Setting to false disables prompts - only use in trusted, controlled environments
677
- # When disabled, the agent can modify files and run commands without asking
678
- export PATCHPAL_MAX_FILE_SIZE=5242880 # Maximum file size in bytes for read/write operations (default: 10485760 = 10MB)
679
- export PATCHPAL_READ_ONLY=true # Prevent all file modifications, analysis-only mode (default: false)
680
- # Useful for: code review, exploration, security audits, CI/CD analysis, or trying PatchPal risk-free
681
- export PATCHPAL_ALLOW_SENSITIVE=true # Allow access to .env, credentials, API keys (default: false - blocked for safety)
682
- # Only enable when working with test/dummy credentials or intentionally managing config files
683
- export PATCHPAL_ALLOW_SUDO=true # Allow sudo commands (default: false - blocked for safety)
684
- # ⚠️ WARNING: Only enable in trusted, controlled environments where sudo is necessary
685
- # When enabled, all privilege escalation blocking is disabled
686
-
687
- # Operational Safety Controls
688
- export PATCHPAL_AUDIT_LOG=false # Log all operations to ~/.patchpal/<repo-name>/audit.log (default: true)
689
- export PATCHPAL_ENABLE_BACKUPS=true # Auto-backup files to ~/.patchpal/<repo-name>/backups/ before modification (default: false)
690
- export PATCHPAL_MAX_OPERATIONS=5000 # Maximum operations per session to prevent infinite loops (default: 10000)
691
- export PATCHPAL_MAX_ITERATIONS=150 # Maximum agent iterations per task (default: 100)
692
- # Increase for very complex multi-file tasks, decrease for testing
693
-
694
- # Customization
695
- export PATCHPAL_SYSTEM_PROMPT=~/.patchpal/my_prompt.md # Use custom system prompt file (default: built-in prompt)
696
- # The file can use template variables like {current_date}, {platform_info}, etc.
697
- # Useful for: custom agent behavior, team standards, domain-specific instructions
698
-
699
- # Web Tool Controls
700
- export PATCHPAL_ENABLE_WEB=false # Enable/disable web search and fetch tools (default: true)
701
- # Set to false for air-gapped or offline environments
702
- export PATCHPAL_WEB_TIMEOUT=60 # Timeout for web requests in seconds (default: 30)
703
- export PATCHPAL_MAX_WEB_SIZE=10485760 # Maximum web content size in bytes (default: 5242880 = 5MB)
704
- export PATCHPAL_MAX_WEB_CHARS=500000 # Maximum characters from web content to prevent context overflow (default: 500000 ≈ 125k tokens)
705
-
706
- # Shell Command Controls
707
- export PATCHPAL_SHELL_TIMEOUT=60 # Timeout for shell commands in seconds (default: 30)
708
- ```
807
+ See the [Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#configuration) section for all available `PATCHPAL_*` environment variables to customize security, permissions, logging, and more.
709
808
 
710
809
  **Permission System:**
711
810
 
@@ -756,7 +855,7 @@ PatchPal automatically manages the context window to prevent "input too long" er
756
855
  **Features:**
757
856
  - **Automatic token tracking**: Monitors context usage in real-time
758
857
  - **Smart pruning**: Removes old tool outputs (keeps last 40k tokens) before resorting to full compaction
759
- - **Auto-compaction**: Summarizes conversation history when approaching 85% capacity
858
+ - **Auto-compaction**: Summarizes conversation history when approaching 75% capacity
760
859
  - **Manual control**: Check status with `/status`, disable with environment variable
761
860
 
762
861
  **Commands:**
@@ -781,20 +880,12 @@ You: /compact
781
880
  ```
782
881
 
783
882
  **Configuration:**
784
- ```bash
785
- # Disable auto-compaction (not recommended for long sessions)
786
- export PATCHPAL_DISABLE_AUTOCOMPACT=true
787
883
 
788
- # Adjust compaction threshold (default: 0.85 = 85%)
789
- export PATCHPAL_COMPACT_THRESHOLD=0.90
790
-
791
- # Adjust pruning thresholds
792
- export PATCHPAL_PRUNE_PROTECT=40000 # Keep last 40k tokens (default)
793
- export PATCHPAL_PRUNE_MINIMUM=20000 # Min tokens to prune (default)
794
-
795
- # Override context limit for testing (useful for testing compaction with small values)
796
- export PATCHPAL_CONTEXT_LIMIT=10000 # Force 10k token limit instead of model default
797
- ```
884
+ See the [Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#configuration) section for context management settings including:
885
+ - `PATCHPAL_DISABLE_AUTOCOMPACT` - Disable auto-compaction
886
+ - `PATCHPAL_COMPACT_THRESHOLD` - Adjust compaction threshold
887
+ - `PATCHPAL_CONTEXT_LIMIT` - Override context limit for testing
888
+ - `PATCHPAL_PRUNE_PROTECT` / `PATCHPAL_PRUNE_MINIMUM` - Pruning controls
798
889
 
799
890
  **Testing Context Management:**
800
891
 
@@ -803,7 +894,7 @@ You can test the context management system with small values to trigger compacti
803
894
  ```bash
804
895
  # Set up small context window for testing
805
896
  export PATCHPAL_CONTEXT_LIMIT=10000 # Force 10k token limit (instead of 200k for Claude)
806
- export PATCHPAL_COMPACT_THRESHOLD=0.75 # Trigger at 75% (instead of 85%)
897
+ export PATCHPAL_COMPACT_THRESHOLD=0.75 # Trigger at 75% (default, but shown for clarity)
807
898
  # Note: System prompt + output reserve = ~6.4k tokens baseline
808
899
  # So 75% of 10k = 7.5k, leaving ~1k for conversation
809
900
  export PATCHPAL_PRUNE_PROTECT=500 # Keep only last 500 tokens of tool outputs
@@ -823,9 +914,9 @@ You: /status
823
914
  # Continue - should see pruning messages
824
915
  You: search for "context" in all files
825
916
  # You should see:
826
- # ⚠️ Context window at 85% capacity. Compacting...
917
+ # ⚠️ Context window at 75% capacity. Compacting...
827
918
  # Pruned old tool outputs (saved ~400 tokens)
828
- # ✓ Compaction complete. Saved 850 tokens (85% → 68%)
919
+ # ✓ Compaction complete. Saved 850 tokens (75% → 58%)
829
920
  ```
830
921
 
831
922
  **How It Works:**
@@ -856,7 +947,7 @@ Context Window Status
856
947
  Usage: 80%
857
948
  [████████████████████████████████████████░░░░░░░░░]
858
949
 
859
- Auto-compaction: Enabled (triggers at 85%)
950
+ Auto-compaction: Enabled (triggers at 75%)
860
951
  ======================================================================
861
952
  ```
862
953
 
@@ -866,10 +957,13 @@ The system ensures you can work for extended periods without hitting context lim
866
957
 
867
958
  **Error: "maximum iterations reached"**
868
959
  - The default number of iterations is 100.
869
- - You can increase by setting the environment variable, `export PATCHPAL_MAX_ITERATIONS`
960
+ - Increase with `export PATCHPAL_MAX_ITERATIONS=200` (see [Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#configuration))
870
961
 
871
962
  **Error: "Context Window Error - Input is too long"**
872
963
  - PatchPal includes automatic context management (compaction) to prevent this error.
873
- - Use `/status` to check your context window usage.
964
+ - **Quick fix:** Run `/compact` to immediately compact the conversation history and free up space.
965
+ - Use `/status` to check your context window usage and see how close you are to the limit.
874
966
  - If auto-compaction is disabled, re-enable it: `unset PATCHPAL_DISABLE_AUTOCOMPACT`
875
- - Context is automatically managed at 85% capacity through pruning and compaction.
967
+ - Context is automatically managed at 75% capacity through pruning and compaction.
968
+ - **Note:** Token estimation may be slightly inaccurate compared to the model's actual counting. If you see this error despite auto-compaction being enabled, the 75% threshold may need to be lowered further for your workload. You can adjust it with `export PATCHPAL_COMPACT_THRESHOLD=0.70` (or lower).
969
+ - See [Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#configuration) for context management settings.
{patchpal-0.1.7 → patchpal-0.3.0}/patchpal/__init__.py RENAMED
@@ -1,6 +1,6 @@
1
1
  """PatchPal - An open-source Claude Code clone implemented purely in Python."""
2
2
 
3
- __version__ = "0.1.7"
3
+ __version__ = "0.3.0"
4
4
 
5
5
  from patchpal.agent import create_agent
6
6
  from patchpal.tools import (