Alat Bash

BangunAlat

Alat bash

Alat bash memungkinkan Claude menjalankan perintah shell dalam sesi bash yang persisten untuk otomasi baris perintah dan operasi sistem.

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

Alat bash memungkinkan Claude menjalankan perintah shell dalam sesi bash yang persisten, memungkinkan operasi sistem, eksekusi skrip, dan otomasi baris perintah. Akses shell adalah kemampuan agen fundamental. Pada Terminal-Bench 2.0, tolok ukur yang mengevaluasi tugas terminal dunia nyata menggunakan validasi hanya shell, Claude menunjukkan peningkatan kinerja yang kuat dengan akses ke sesi bash yang persisten.

Ikhtisar

Alat bash menyediakan Claude dengan:

Sesi bash persisten yang mempertahankan status
Kemampuan menjalankan perintah shell apa pun
Akses ke variabel lingkungan dan direktori kerja
Kemampuan perantaian perintah dan skrip

Untuk dukungan model, lihat Referensi alat.

Kasus penggunaan

Alur kerja pengembangan: Jalankan perintah build, tes, dan alat pengembangan
Otomasi sistem: Jalankan skrip, kelola file, otomatisasi tugas
Pemrosesan data: Proses file, jalankan skrip analisis, kelola dataset
Penyiapan lingkungan: Instal paket, konfigurasi lingkungan

Mulai cepat

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[{"type": "bash_20250124", "name": "bash"}],
    messages=[
        {"role": "user", "content": "List all Python files in the current directory."}
    ],
)

print(response)

Cara kerjanya

Alat bash mempertahankan sesi yang persisten:

Claude menentukan perintah apa yang akan dijalankan
Anda menjalankan perintah dalam shell bash
Kembalikan output (stdout dan stderr) ke Claude
Status sesi persisten antara perintah (variabel lingkungan, direktori kerja)

Parameter

Parameter	Diperlukan	Deskripsi
`command`	Ya*	Perintah bash yang akan dijalankan
`restart`	Tidak	Atur ke `true` untuk memulai ulang sesi bash

*Diperlukan kecuali menggunakan restart

Contoh: Otomasi multi-langkah

Claude dapat merantai perintah untuk menyelesaikan tugas kompleks:

Permintaan pengguna:
"Install the requests library and create a simple Python script that
fetches a joke from an API, then run it."

Alat Claude menggunakan:
1. Instal paket
   {"command": "pip install requests"}

2. Buat skrip
   {"command": "cat > fetch_joke.py << 'EOF'\nimport requests\nresponse = requests.get('https://official-joke-api.appspot.com/random_joke')\njoke = response.json()\nprint(f\"Setup: {joke['setup']}\")\nprint(f\"Punchline: {joke['punchline']}\")\nEOF"}

3. Jalankan skrip
   {"command": "python fetch_joke.py"}

Sesi mempertahankan status antara perintah, jadi file yang dibuat di langkah 2 tersedia di langkah 3.

Implementasikan alat bash

Alat bash diimplementasikan sebagai alat tanpa skema. Saat menggunakan alat ini, Anda tidak perlu menyediakan skema input seperti alat lainnya; skema dibangun ke dalam model Claude dan tidak dapat dimodifikasi.

Siapkan lingkungan bash

Buat sesi bash persisten yang dapat berinteraksi dengan Claude:

import subprocess
import threading
import queue


class BashSession:
    def __init__(self):
        self.process = subprocess.Popen(
            ["/bin/bash"],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            bufsize=0,
        )
        self.output_queue = queue.Queue()
        self.error_queue = queue.Queue()
        self._start_readers()

Tangani eksekusi perintah

Buat fungsi untuk menjalankan perintah dan menangkap output:

def execute_command(self, command):
    # Send command to bash
    self.process.stdin.write(command + "\n")
    self.process.stdin.flush()

    # Capture output with timeout
    output = self._read_output(timeout=10)
    return output

Proses panggilan alat Claude

Ekstrak dan jalankan perintah dari respons Claude:

for content in response.content:
    if content.type == "tool_use" and content.name == "bash":
        if content.input.get("restart"):
            bash_session.restart()
            result = "Bash session restarted"
        else:
            command = content.input.get("command")
            result = bash_session.execute_command(command)

        # Return result to Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

Implementasikan langkah-langkah keamanan

Tambahkan validasi dan pembatasan. Gunakan daftar izin daripada daftar blokir, karena daftar blokir mudah dilewati. Tolak operator shell sehingga perintah berantai tidak dapat melewati daftar izin:

import shlex

ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}


def validate_command(command):
    # Allow only commands from an explicit allowlist
    try:
        tokens = shlex.split(command)
    except ValueError:
        return False, "Could not parse command"

    if not tokens:
        return False, "Empty command"

    executable = tokens[0]
    if executable not in ALLOWED_COMMANDS:
        return False, f"Command '{executable}' is not in the allowlist"

    # Reject shell operators that would chain additional commands
    for token in tokens[1:]:
        if token in SHELL_OPERATORS or token.startswith(("$", "`")):
            return False, f"Shell operator '{token}' is not allowed"

    return True, None

Pemeriksaan ini adalah garis pertahanan pertama. Untuk isolasi yang lebih kuat, jalankan perintah yang divalidasi dengan shell=False dan teruskan shlex.split(command) sebagai daftar argumen, sehingga shell tidak pernah menginterpretasi string.

Tangani kesalahan

Saat mengimplementasikan alat bash, tangani berbagai skenario kesalahan:

Ikuti praktik terbaik implementasi

Keamanan

Alat bash menyediakan akses sistem langsung. Implementasikan langkah-langkah keamanan penting ini:

Berjalan di lingkungan terisolasi (Docker/VM)
Mengimplementasikan penyaringan perintah dan daftar izin
Menetapkan batas sumber daya (CPU, memori, disk)
Mencatat semua perintah yang dijalankan

Rekomendasi utama

Gunakan ulimit untuk menetapkan batasan sumber daya
Saring perintah berbahaya (sudo, rm -rf, dll.)
Jalankan dengan izin pengguna minimal
Pantau dan catat semua eksekusi perintah

Harga

The bash tool adds 245 input tokens to your API calls.

Additional tokens are consumed by:

Command outputs (stdout/stderr)
Error messages
Large file contents

Lihat harga penggunaan alat untuk detail harga lengkap.

Pola umum

Alur kerja pengembangan

Menjalankan tes: pytest && coverage report
Membangun proyek: npm install && npm run build
Operasi Git: git status && git add . && git commit -m "message"

Checkpointing berbasis Git

Git berfungsi sebagai mekanisme pemulihan terstruktur dalam alur kerja agen jangka panjang, bukan hanya cara untuk menyimpan perubahan:

Tangkap baseline: Sebelum pekerjaan agen dimulai, komit status saat ini. Ini adalah titik awal yang diketahui baik.
Komit per fitur: Setiap fitur yang selesai mendapat komitnya sendiri. Ini berfungsi sebagai titik rollback jika ada yang salah nanti.
Rekonstruksi status saat memulai sesi: Baca git log bersama file kemajuan untuk memahami apa yang sudah dilakukan dan apa yang akan datang selanjutnya.
Kembalikan saat gagal: Jika pekerjaan menjadi kacau, git checkout kembali ke komit terakhir yang baik daripada mencoba men-debug status yang rusak.

Operasi file

Memproses data: wc -l *.csv && ls -lh *.csv
Mencari file: find . -name "*.py" | xargs grep "pattern"
Membuat cadangan: tar -czf backup.tar.gz ./data

Tugas sistem

Memeriksa sumber daya: df -h && free -m
Manajemen proses: ps aux | grep python
Penyiapan lingkungan: export PATH=$PATH:/new/path && echo $PATH

Keterbatasan

Tidak ada perintah interaktif: Tidak dapat menangani vim, less, atau prompt kata sandi
Tidak ada aplikasi GUI: Hanya baris perintah
Cakupan sesi: Status sesi bash adalah sisi klien. API tidak memiliki status. Aplikasi Anda bertanggung jawab untuk mempertahankan sesi shell antara giliran.
Batas output: Output besar mungkin dipotong
Tidak ada streaming: Hasil dikembalikan setelah penyelesaian

Menggabungkan dengan alat lain

Alat bash paling kuat ketika digabungkan dengan editor teks dan alat lainnya.

Jika Anda juga menggunakan alat eksekusi kode, Claude memiliki akses ke dua lingkungan eksekusi terpisah: sesi bash lokal Anda dan kontainer sandbox Anthropic. Status tidak dibagikan di antara mereka. Lihat Menggunakan eksekusi kode dengan alat eksekusi lainnya untuk panduan tentang meminta Claude membedakan antara lingkungan.

Langkah berikutnya

Ikhtisar penggunaan alat

Pelajari tentang penggunaan alat dengan Claude

Alat editor teks

Lihat dan edit file teks dengan Claude

Was this page helpful?

BangunAlat

Alat bash

Alat bash memungkinkan Claude menjalankan perintah shell dalam sesi bash yang persisten untuk otomasi baris perintah dan operasi sistem.

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

Ikhtisar

Alat bash menyediakan Claude dengan:

Sesi bash persisten yang mempertahankan status
Kemampuan menjalankan perintah shell apa pun
Akses ke variabel lingkungan dan direktori kerja
Kemampuan perantaian perintah dan skrip

Untuk dukungan model, lihat Referensi alat.

Kasus penggunaan

Alur kerja pengembangan: Jalankan perintah build, tes, dan alat pengembangan
Otomasi sistem: Jalankan skrip, kelola file, otomatisasi tugas
Pemrosesan data: Proses file, jalankan skrip analisis, kelola dataset
Penyiapan lingkungan: Instal paket, konfigurasi lingkungan

Mulai cepat

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[{"type": "bash_20250124", "name": "bash"}],
    messages=[
        {"role": "user", "content": "List all Python files in the current directory."}
    ],
)

print(response)

Cara kerjanya

Alat bash mempertahankan sesi yang persisten:

Claude menentukan perintah apa yang akan dijalankan
Anda menjalankan perintah dalam shell bash
Kembalikan output (stdout dan stderr) ke Claude
Status sesi persisten antara perintah (variabel lingkungan, direktori kerja)

Parameter

Parameter	Diperlukan	Deskripsi
`command`	Ya*	Perintah bash yang akan dijalankan
`restart`	Tidak	Atur ke `true` untuk memulai ulang sesi bash

*Diperlukan kecuali menggunakan restart

Contoh: Otomasi multi-langkah

Claude dapat merantai perintah untuk menyelesaikan tugas kompleks:

Permintaan pengguna:
"Install the requests library and create a simple Python script that
fetches a joke from an API, then run it."

Alat Claude menggunakan:
1. Instal paket
   {"command": "pip install requests"}

2. Buat skrip
   {"command": "cat > fetch_joke.py << 'EOF'\nimport requests\nresponse = requests.get('https://official-joke-api.appspot.com/random_joke')\njoke = response.json()\nprint(f\"Setup: {joke['setup']}\")\nprint(f\"Punchline: {joke['punchline']}\")\nEOF"}

3. Jalankan skrip
   {"command": "python fetch_joke.py"}

Sesi mempertahankan status antara perintah, jadi file yang dibuat di langkah 2 tersedia di langkah 3.

Implementasikan alat bash

Siapkan lingkungan bash

Buat sesi bash persisten yang dapat berinteraksi dengan Claude:

import subprocess
import threading
import queue


class BashSession:
    def __init__(self):
        self.process = subprocess.Popen(
            ["/bin/bash"],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            bufsize=0,
        )
        self.output_queue = queue.Queue()
        self.error_queue = queue.Queue()
        self._start_readers()

Tangani eksekusi perintah

Buat fungsi untuk menjalankan perintah dan menangkap output:

def execute_command(self, command):
    # Send command to bash
    self.process.stdin.write(command + "\n")
    self.process.stdin.flush()

    # Capture output with timeout
    output = self._read_output(timeout=10)
    return output

Proses panggilan alat Claude

Ekstrak dan jalankan perintah dari respons Claude:

for content in response.content:
    if content.type == "tool_use" and content.name == "bash":
        if content.input.get("restart"):
            bash_session.restart()
            result = "Bash session restarted"
        else:
            command = content.input.get("command")
            result = bash_session.execute_command(command)

        # Return result to Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

Implementasikan langkah-langkah keamanan

Tambahkan validasi dan pembatasan. Gunakan daftar izin daripada daftar blokir, karena daftar blokir mudah dilewati. Tolak operator shell sehingga perintah berantai tidak dapat melewati daftar izin:

import shlex

ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}


def validate_command(command):
    # Allow only commands from an explicit allowlist
    try:
        tokens = shlex.split(command)
    except ValueError:
        return False, "Could not parse command"

    if not tokens:
        return False, "Empty command"

    executable = tokens[0]
    if executable not in ALLOWED_COMMANDS:
        return False, f"Command '{executable}' is not in the allowlist"

    # Reject shell operators that would chain additional commands
    for token in tokens[1:]:
        if token in SHELL_OPERATORS or token.startswith(("$", "`")):
            return False, f"Shell operator '{token}' is not allowed"

    return True, None

Tangani kesalahan

Saat mengimplementasikan alat bash, tangani berbagai skenario kesalahan:

Ikuti praktik terbaik implementasi

Keamanan

Alat bash menyediakan akses sistem langsung. Implementasikan langkah-langkah keamanan penting ini:

Berjalan di lingkungan terisolasi (Docker/VM)
Mengimplementasikan penyaringan perintah dan daftar izin
Menetapkan batas sumber daya (CPU, memori, disk)
Mencatat semua perintah yang dijalankan

Rekomendasi utama

Gunakan ulimit untuk menetapkan batasan sumber daya
Saring perintah berbahaya (sudo, rm -rf, dll.)
Jalankan dengan izin pengguna minimal
Pantau dan catat semua eksekusi perintah

Harga

The bash tool adds 245 input tokens to your API calls.

Additional tokens are consumed by:

Command outputs (stdout/stderr)
Error messages
Large file contents

Lihat harga penggunaan alat untuk detail harga lengkap.

Pola umum

Alur kerja pengembangan

Menjalankan tes: pytest && coverage report
Membangun proyek: npm install && npm run build
Operasi Git: git status && git add . && git commit -m "message"

Checkpointing berbasis Git

Git berfungsi sebagai mekanisme pemulihan terstruktur dalam alur kerja agen jangka panjang, bukan hanya cara untuk menyimpan perubahan:

Tangkap baseline: Sebelum pekerjaan agen dimulai, komit status saat ini. Ini adalah titik awal yang diketahui baik.
Komit per fitur: Setiap fitur yang selesai mendapat komitnya sendiri. Ini berfungsi sebagai titik rollback jika ada yang salah nanti.
Rekonstruksi status saat memulai sesi: Baca git log bersama file kemajuan untuk memahami apa yang sudah dilakukan dan apa yang akan datang selanjutnya.
Kembalikan saat gagal: Jika pekerjaan menjadi kacau, git checkout kembali ke komit terakhir yang baik daripada mencoba men-debug status yang rusak.

Operasi file

Memproses data: wc -l *.csv && ls -lh *.csv
Mencari file: find . -name "*.py" | xargs grep "pattern"
Membuat cadangan: tar -czf backup.tar.gz ./data

Tugas sistem

Memeriksa sumber daya: df -h && free -m
Manajemen proses: ps aux | grep python
Penyiapan lingkungan: export PATH=$PATH:/new/path && echo $PATH

Keterbatasan

Tidak ada perintah interaktif: Tidak dapat menangani vim, less, atau prompt kata sandi
Tidak ada aplikasi GUI: Hanya baris perintah
Cakupan sesi: Status sesi bash adalah sisi klien. API tidak memiliki status. Aplikasi Anda bertanggung jawab untuk mempertahankan sesi shell antara giliran.
Batas output: Output besar mungkin dipotong
Tidak ada streaming: Hasil dikembalikan setelah penyelesaian

Menggabungkan dengan alat lain

Alat bash paling kuat ketika digabungkan dengan editor teks dan alat lainnya.

Langkah berikutnya

Ikhtisar penggunaan alat

Pelajari tentang penggunaan alat dengan Claude

Alat editor teks

Lihat dan edit file teks dengan Claude

Was this page helpful?

Ikhtisar

Kasus penggunaan

Mulai cepat

Cara kerjanya

Parameter

Contoh penggunaan

Contoh: Otomasi multi-langkah

Implementasikan alat bash

Tangani kesalahan

Batas waktu eksekusi perintah

Perintah tidak ditemukan

Izin ditolak

Ikuti praktik terbaik implementasi

Gunakan batas waktu perintah

Pertahankan status sesi

Tangani output besar

Catat semua perintah

Sanitasi output

Keamanan

Rekomendasi utama

Harga

Pola umum

Alur kerja pengembangan

Checkpointing berbasis Git

Operasi file

Tugas sistem

Keterbatasan

Menggabungkan dengan alat lain

Langkah berikutnya

Ikhtisar

Kasus penggunaan

Mulai cepat

Cara kerjanya

Parameter

Contoh penggunaan

Contoh: Otomasi multi-langkah

Implementasikan alat bash

Tangani kesalahan

Batas waktu eksekusi perintah

Perintah tidak ditemukan

Izin ditolak

Ikuti praktik terbaik implementasi

Gunakan batas waktu perintah

Pertahankan status sesi

Tangani output besar

Catat semua perintah

Sanitasi output

Keamanan

Rekomendasi utama

Harga

Pola umum

Alur kerja pengembangan

Checkpointing berbasis Git

Operasi file

Tugas sistem

Keterbatasan

Menggabungkan dengan alat lain

Langkah berikutnya