| Name | iterm2-focus JSON |
| Version |
0.0.11
JSON |
| download |
| home_page | None |
| Summary | Focus iTerm2 sessions by ID |
| upload_time | 2025-07-13 08:02:35 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
cli
focus
iterm2
macos
terminal
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# iterm2-focus
Focus iTerm2 sessions by ID from the command line.
## Features
- Focus any iTerm2 session by its ID
- Get the current session ID
- List all available sessions
- Focus the current session (useful when returning from other applications)
## Installation
```bash
pip install iterm2-focus
```
Or using [uv](https://github.com/astral-sh/uv):
```bash
uv pip install iterm2-focus
```
## Quick Usage (without installation)
You can run `iterm2-focus` directly without installing using `uvx`:
```bash
# List all sessions
uvx iterm2-focus --list
# Focus a specific session
uvx iterm2-focus <session-id>
# Get current session ID
uvx iterm2-focus --get-current
```
## Prerequisites
1. **macOS** with iTerm2 installed
2. **Python 3.10** or later
3. **iTerm2 Python API** must be enabled:
- Open iTerm2
- Go to *Settings* → *General* → *Magic*
- Check "Enable Python API"
- Restart iTerm2
## Usage
### Focus a specific session
```bash
iterm2-focus w0t0p0:12345678-1234-1234-1234-123456789012
```
### Focus the current session
Useful when returning from another application:
```bash
iterm2-focus --current
# or
iterm2-focus -c
```
### Get the current session ID
```bash
iterm2-focus --get-current
# or
iterm2-focus -g
```
### List all sessions
```bash
iterm2-focus --list
# or
iterm2-focus -l
```
### Additional options
```bash
# Show version
iterm2-focus --version
# Quiet mode (suppress output)
iterm2-focus -q <session-id>
# Help
iterm2-focus --help
```
## MCP Server Mode
`iterm2-focus` can run as an MCP (Model Context Protocol) server, allowing LLM applications like Claude Desktop to control iTerm2 sessions.
### Starting the MCP server
```bash
# Install with MCP support
pip install 'iterm2-focus[mcp]'
# Start the MCP server
iterm2-focus --mcp
```
### Configuring Claude Desktop
Using Claude Code CLI (recommended):
```bash
# Add the MCP server using uvx (no installation required)
claude mcp add iterm2-focus uvx iterm2-focus --mcp
# Or if you have it installed locally
claude mcp add iterm2-focus iterm2-focus --mcp
```
Or manually add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"iterm2-focus": {
"command": "uvx",
"args": ["iterm2-focus", "--mcp"]
}
}
}
```
Or if you have it installed locally:
```json
{
"mcpServers": {
"iterm2-focus": {
"command": "iterm2-focus",
"args": ["--mcp"]
}
}
}
```
### Available MCP tools
- **list_sessions**: List all iTerm2 sessions with their IDs and metadata
- **focus_session**: Focus a specific session by ID
- **get_current_session**: Get information about the currently focused session
## Examples
### Save and restore focus
```bash
# Save current session ID
SAVED_SESSION=$(iterm2-focus -g -q)
# ... do other work ...
# Return to saved session
iterm2-focus $SAVED_SESSION
```
### Focus a session from another application
```applescript
-- AppleScript example
do shell script "iterm2-focus w0t0p0:12345678-1234-1234-1234-123456789012"
```
## Development
### Setup
```bash
# Clone the repository
git clone https://github.com/mkusaka/iterm2-focus
cd iterm2-focus
# Create virtual environment with uv
uv venv
uv pip install -e ".[dev]"
```
### Testing
```bash
# Run tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=iterm2_focus
# Type checking
uv run mypy src
# Linting and formatting
uv run ruff check src tests
uv run black src tests
```
### Building
```bash
# Build the package
uv build
# Upload to PyPI
uv publish
```
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Troubleshooting
### "Failed to connect to iTerm2" error
Make sure iTerm2's Python API is enabled (see Prerequisites).
### "Session not found" error
Verify the session ID using `iterm2-focus --list` to see all available sessions.
### Permission errors
On first run, macOS may ask for permission to control iTerm2. Please allow this in System Preferences.
## Author
mkusaka <hinoshita1992@gmail.com>
Raw data
{
"_id": null,
"home_page": null,
"name": "iterm2-focus",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "cli, focus, iterm2, macos, terminal",
"author": null,
"author_email": "mkusaka <hinoshita1992@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/82/c7/9a1c3b60be252fa26927ee1b637b9a1e48e0f937ba1383a7d684cbcb7a6a/iterm2_focus-0.0.11.tar.gz",
"platform": null,
"description": "# iterm2-focus\n\nFocus iTerm2 sessions by ID from the command line.\n\n## Features\n\n- Focus any iTerm2 session by its ID\n- Get the current session ID\n- List all available sessions\n- Focus the current session (useful when returning from other applications)\n\n## Installation\n\n```bash\npip install iterm2-focus\n```\n\nOr using [uv](https://github.com/astral-sh/uv):\n\n```bash\nuv pip install iterm2-focus\n```\n\n## Quick Usage (without installation)\n\nYou can run `iterm2-focus` directly without installing using `uvx`:\n\n```bash\n# List all sessions\nuvx iterm2-focus --list\n\n# Focus a specific session\nuvx iterm2-focus <session-id>\n\n# Get current session ID\nuvx iterm2-focus --get-current\n```\n\n## Prerequisites\n\n1. **macOS** with iTerm2 installed\n2. **Python 3.10** or later\n3. **iTerm2 Python API** must be enabled:\n - Open iTerm2\n - Go to *Settings* \u2192 *General* \u2192 *Magic*\n - Check \"Enable Python API\"\n - Restart iTerm2\n\n## Usage\n\n### Focus a specific session\n\n```bash\niterm2-focus w0t0p0:12345678-1234-1234-1234-123456789012\n```\n\n### Focus the current session\n\nUseful when returning from another application:\n\n```bash\niterm2-focus --current\n# or\niterm2-focus -c\n```\n\n### Get the current session ID\n\n```bash\niterm2-focus --get-current\n# or\niterm2-focus -g\n```\n\n### List all sessions\n\n```bash\niterm2-focus --list\n# or\niterm2-focus -l\n```\n\n### Additional options\n\n```bash\n# Show version\niterm2-focus --version\n\n# Quiet mode (suppress output)\niterm2-focus -q <session-id>\n\n# Help\niterm2-focus --help\n```\n\n## MCP Server Mode\n\n`iterm2-focus` can run as an MCP (Model Context Protocol) server, allowing LLM applications like Claude Desktop to control iTerm2 sessions.\n\n### Starting the MCP server\n\n```bash\n# Install with MCP support\npip install 'iterm2-focus[mcp]'\n\n# Start the MCP server\niterm2-focus --mcp\n```\n\n### Configuring Claude Desktop\n\nUsing Claude Code CLI (recommended):\n\n```bash\n# Add the MCP server using uvx (no installation required)\nclaude mcp add iterm2-focus uvx iterm2-focus --mcp\n\n# Or if you have it installed locally\nclaude mcp add iterm2-focus iterm2-focus --mcp\n```\n\nOr manually add to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"iterm2-focus\": {\n \"command\": \"uvx\",\n \"args\": [\"iterm2-focus\", \"--mcp\"]\n }\n }\n}\n```\n\nOr if you have it installed locally:\n\n```json\n{\n \"mcpServers\": {\n \"iterm2-focus\": {\n \"command\": \"iterm2-focus\",\n \"args\": [\"--mcp\"]\n }\n }\n}\n```\n\n### Available MCP tools\n\n- **list_sessions**: List all iTerm2 sessions with their IDs and metadata\n- **focus_session**: Focus a specific session by ID\n- **get_current_session**: Get information about the currently focused session\n\n## Examples\n\n### Save and restore focus\n\n```bash\n# Save current session ID\nSAVED_SESSION=$(iterm2-focus -g -q)\n\n# ... do other work ...\n\n# Return to saved session\niterm2-focus $SAVED_SESSION\n```\n\n### Focus a session from another application\n\n```applescript\n-- AppleScript example\ndo shell script \"iterm2-focus w0t0p0:12345678-1234-1234-1234-123456789012\"\n```\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/mkusaka/iterm2-focus\ncd iterm2-focus\n\n# Create virtual environment with uv\nuv venv\nuv pip install -e \".[dev]\"\n```\n\n### Testing\n\n```bash\n# Run tests\nuv run pytest\n\n# Run tests with coverage\nuv run pytest --cov=iterm2_focus\n\n# Type checking\nuv run mypy src\n\n# Linting and formatting\nuv run ruff check src tests\nuv run black src tests\n```\n\n### Building\n\n```bash\n# Build the package\nuv build\n\n# Upload to PyPI\nuv publish\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Troubleshooting\n\n### \"Failed to connect to iTerm2\" error\n\nMake sure iTerm2's Python API is enabled (see Prerequisites).\n\n### \"Session not found\" error\n\nVerify the session ID using `iterm2-focus --list` to see all available sessions.\n\n### Permission errors\n\nOn first run, macOS may ask for permission to control iTerm2. Please allow this in System Preferences.\n\n## Author\n\nmkusaka <hinoshita1992@gmail.com>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Focus iTerm2 sessions by ID",
"version": "0.0.11",
"project_urls": {
"Bug Tracker": "https://github.com/mkusaka/iterm2-focus/issues",
"Documentation": "https://github.com/mkusaka/iterm2-focus#readme",
"Homepage": "https://github.com/mkusaka/iterm2-focus",
"Source Code": "https://github.com/mkusaka/iterm2-focus"
},
"split_keywords": [
"cli",
" focus",
" iterm2",
" macos",
" terminal"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "96f2f91164b3dbcd32f5225bf8b61a619804e69e83d8c610820bdce150e34453",
"md5": "e2363b290e127917ca652ba57c4aa59e",
"sha256": "db27f59952288849cddeb26f3fff47b45d239661d06e4d9668063fac449b3948"
},
"downloads": -1,
"filename": "iterm2_focus-0.0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2363b290e127917ca652ba57c4aa59e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11899,
"upload_time": "2025-07-13T08:02:34",
"upload_time_iso_8601": "2025-07-13T08:02:34.275113Z",
"url": "https://files.pythonhosted.org/packages/96/f2/f91164b3dbcd32f5225bf8b61a619804e69e83d8c610820bdce150e34453/iterm2_focus-0.0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "82c79a1c3b60be252fa26927ee1b637b9a1e48e0f937ba1383a7d684cbcb7a6a",
"md5": "c4b00eb334f985094ec313c33c7855e0",
"sha256": "9b4b69b64ccc809daf0dce89724cc9ce4afab030c9cfc742b3f033520bb040d6"
},
"downloads": -1,
"filename": "iterm2_focus-0.0.11.tar.gz",
"has_sig": false,
"md5_digest": "c4b00eb334f985094ec313c33c7855e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 92264,
"upload_time": "2025-07-13T08:02:35",
"upload_time_iso_8601": "2025-07-13T08:02:35.350987Z",
"url": "https://files.pythonhosted.org/packages/82/c7/9a1c3b60be252fa26927ee1b637b9a1e48e0f937ba1383a7d684cbcb7a6a/iterm2_focus-0.0.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 08:02:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mkusaka",
"github_project": "iterm2-focus",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "iterm2-focus"
}
